VTEX Return App
- Open the VTEX App Store and install this app on your store, or run the following command on VTEX toolbelt:
vtex install [email protected]
- From the left side access the
Returns > Requests
page. The first time you access it, the application creates the masterdata schema and settings it needs automatically.
- Go to
Returns > Returns Settings
and fill up the form with the settings you need.Max days:
The maximum number of days that customers can request the return of products, from the moment the order was invoiced.Terms and conditions URL:
The URL of the page with the return terms and conditions. The customer can access this URL from the form they fill out to request a return.- If you have the terms on conditions page on
http://example.com/terms-and-conditions
it's enough for you to type just/terms-and-conditions
- If you have the terms on conditions page on
Excluded categories:
Products that are in those categories will not be eligible for returnPayment methods:
Display or hide payment methods. You should have at least one option selected.Custom return options (OPTIONAL):
This table allows to create custom reasons as return options, with the addition to have custom max allowed dates for each one. If none added, the default reasons will be used
The return application serves the necessary functionalities for requesting returns from customers, and their processing by the administrators of the online store.
The application can be installed using the following command in VTEX Toolbelt: vtex install [email protected]
After the installation you must access the Returns > Requests
page from the admin menu. At this point, the application creates the masterdata schema and email templates automatically.
- The email templates are generated by sending a POST request to
/api/template-render/pvt/templates
- The masterdata schema are generated using the
clients.masterdata.createOrUpdateSchema
method from theContext
There are 5 schemas in masterdata:
Schema name | Fields | Type field |
---|---|---|
returnSettings |
maxDays excludedCategories termsUrl options type |
settings |
returnRequests |
userId orderId name email phoneNumber country locality address totalPrice paymentMethod extraComment voucherCode refundedAmount iban status dateSubmitted type |
request |
returnProducts |
refundId orderId userId imageUrl skuId sku manufacturerCode productId ean brandId brandName skuName unitPrice quantity totalPrice goodProducts status dateSubmitted type |
product |
returnComments |
refundId status comment visibleForCustomer submittedBy dateSubmitted type |
comment |
returnStatusHistory |
refundId status submittedBy dateSubmitted type |
statusHistory |
After this step the administrators will go to Returns > Settings
page and fill up the form with the settings they want.
The application use 6 routes. 3 routes for admins and 3 for customers
Returns > Settings
(the page where administrators configure application settings)Returns > Requests
(here the return requests will be displayed in a table)Returns > Requests > Details
(on this page the details of the return request are displayed, the status of the request can be modified and comments can be added for each status)
My returns
(on this page the customer can see all his return requests)My returns > Add
(from this page the customer adds a new return request)My returns > Details
(on this page the customer can see all the information about the return request. This page is very similar to the admin page, except that the customer does not have access to change the status of the return request or change the status of the products)
Payment method | Description |
---|---|
Credit or debit card |
This option is only available if the customer has paid with the card |
Bank transfer |
For this option the IBAN input will be available for customer. This field is required and has a specific validation |
Voucher |
If the customer choose this option, a coupon will be generated automatically when the request reach the Amount refunded status |
Status | Description | Next status |
---|---|---|
New |
This is the default status for a return request | Picked up from client |
Picked up from client |
The request reaches this state when the administrators receive the package from the client | Pending verification |
Pending verification |
In this state, administrators check the products returned by the customer. The "Verify package" button will be available on the return details page, above the product table. | Approved Partially approved Denied |
Approved |
The return request reaches this state if all products are in good condition. | Amount refunded |
Partially approved |
The return request reaches this state if the number of products in good condition is less than the total number of products in the return request. | Amount refunded |
Denied |
The return request reaches this state if there are no products in good condition | - |
Amount refunded |
This is the last state for a return request, if it has not been denied. The administrators will move the request in this state after making the payment to the client (by card or by bank transfer). If the customer requested the return of the money by voucher, the voucher will be generated automatically when the request reach this state. | - |
https://{accountName}.{environment}.com.br/no-cache/no-cache/returns/api/get-requests
Url Parameters:
Param | Type | Required | Default | Values |
---|---|---|---|---|
page | number | no | 1 | |
limit | number | no | 10 | |
status | string | no | - | New /Picked up from client /Pending verification /Approved /Partially approved /Denied /Refunded |
dateStart | date YYYY-MM-DD | no | - | |
dateEnd | date YYYY-MM-DD | no | - |
[
{
"id": "request_id_1",
"orderId": "1000000000000-01",
"totalPrice": 9400,
"refundedAmount": 0,
"status": "New",
"dateSubmitted": "2021-05-07T10:02:06.983Z",
"extraComment": "Extra request comment with a max span of 250 chars"
"customerInfo": {
"name": "Customer Name",
"email": "[email protected]",
"phoneNumber": "0720000000",
"country": "Romania",
"locality": "Constanta",
"address": "Str. mea 1, bl.1, sc.2, ap.3"
},
"paymentInfo": {
"paymentMethod": "giftCard",
"iban": "",
"giftCardCode": "",
"giftCardId": ""
},
"products": [
{
"image": "Product image url",
"refId": "sku reference code",
"skuId": "sku id",
"brandName": "",
"brandId": "",
"manufacturerCode": "",
"productId": "product id",
"name": "Product Name",
"unitPrice": 3000,
"quantity": 2,
"totalPrice": 6000,
"goodProducts": 0,
"reasonCode": "reasonBetterPrice",
"reasonText": "",
"status": "New"
}
],
"statusHistory": [
{
"status": "New",
"dateSubmitted": "2021-05-07T10:02:07.432Z",
"submittedBy": "Submitted by name"
}
],
"comments": []
},
{
"id": "request_id_2",
"orderId": "1000000000001-01",
"totalPrice": 1000,
"refundedAmount": 0,
"status": "Pending verification",
"dateSubmitted": "2021-05-07T10:02:06.983Z",
"extraComment": ""
"customerInfo": {
"name": "Customer Name",
"email": "[email protected]",
"phoneNumber": "0720000000",
"country": "Romania",
"locality": "Iasi",
"address": "Str. mea 1, bl.1, sc.2, ap.3"
},
"paymentInfo": {
"paymentMethod": "bankTransfer",
"iban": "RO00 0000 0000 0000 0000",
"giftCardCode": "",
"giftCardId": ""
},
"products": [
{
"image": "Product image url",
"refId": "sku reference code",
"skuId": "sku id",
"brandName": "",
"brandId": "",
"manufacturerCode": "",
"productId": "product id",
"name": "Product Name",
"unitPrice": 3000,
"quantity": 2,
"totalPrice": 6000,
"goodProducts": 0,
"reasonCode": "reasonBetterPrice",
"reasonText": "",
"status": "New"
}
],
"statusHistory": [
{
"status": "New",
"dateSubmitted": "2021-05-07T10:02:07.432Z",
"submittedBy": "Submitted by name"
},
{
"status": "Picked up from client",
"dateSubmitted": "2021-05-07T10:02:07.432Z",
"submittedBy": "Submitted by name"
},
{
"status": "Pending Verification",
"dateSubmitted": "2021-05-07T10:02:07.432Z",
"submittedBy": "Submitted by name"
}
],
"comments": []
}
]
https://{accountName}.{environment}.com.br/no-cache/returns/api/get-request/{request_id}
{
"success": true,
"errorMessage": "",
"data": {
"id": "request_id",
"orderId": "1000000000000-01",
"totalPrice": 4700,
"refundedAmount": 0,
"status": "Denied",
"dateSubmitted": "2021-05-05T07:44:50.443Z",
"extraComment": "Extra request comment with a max span of 250 chars"
"customerInfo": {
"name": "Customer fullname",
"email": "[email protected]",
"phoneNumber": "0720000000",
"country": "Romania",
"locality": "Contanta",
"address": "Full address"
},
"paymentInfo": {
"paymentMethod": "giftCard",
"iban": "",
"giftCardCode": "",
"giftCardId": ""
},
"products": [
{
"image": "https://customsoft.vteximg.com.br/arquivos/ids/177023-55-55/image-a2759e73daed4c73b98c4f57f46929bd.jpg?v=637523674108530000",
"refId": "REPARATIILE CASEI MELE-13",
"skuId": 'sku id',
"brandName": 'brand',
"brandId": 'brand id',
"manufacturerCode": 'manufacturer code',
"productId": 1,
"name": "REPARATIILE CASEI MELE",
"unitPrice": 1700,
"quantity": 1,
"totalPrice": 1700,
"goodProducts": 0,
"reasonCode": "reasonBetterPrice",
"reasonText": "",
"status": "New"
}
],
"statusHistory": [
{
"status": "Pending verification",
"dateSubmitted": "2021-05-07T09:32:08.673Z",
"submittedBy": ""
}
],
"comments": []
}
}
https://{accountName}.{environment}.com.br/no-cache/returns/api/add-comment/{request_id}
Body Parameters:
Param | Type | Required | Default |
---|---|---|---|
submittedBy | string | yes | |
comment | string | yes | |
visibleForCustomer | boolean | no | false |
Body example:
{
"submittedBy": "your fullname here",
"comment": "Comment Here",
"visibleForCustomer": true
}
https://{accountName}.{environment}.com/no-cache/returns/api/verify-package/{request_id}
Body Parameters:
Param | Type | Required | Default |
---|---|---|---|
restockFee | number | no | 0 |
refundedShippingValue | number | no | 0 |
After using this API you can check the results using the Get request by id
API
Body example:
{
"restockFee": 100,
"refundedShippingValue": 20
}
{
"success": true,
"errorMessage": "",
"totalRefundAmount": 200.36,
"newTotalRefundAmount": 120.36000000000001,
"refundedProducts": [
{
"id": "53d20749-2de3-11ec-82ac-1670783e7e4f",
"createdIn": "2021-10-15T18:11:34.0460916Z",
"refundId": "4fd9fab1-2de3-11ec-82ac-0a07788173f1",
"orderId": "1164033206599-01",
"userId": "3a1d2c0a-199c-4c98-bc72-ba8b2de0afa3",
"imageUrl": "https://sandboxusdev.vteximg.com.br/arquivos/ids/189110-55-55/Cloud-White---Hazy-Orange---Core-Black---10-1.jpg?v=637532549058070000",
"sku": "80008134",
"skuId": "Adidas01-Colors-10V5",
"productId": "80008068",
"ean": "C12345-10V5",
"brandId": "2000012",
"brandName": "AdidasV2",
"skuName": "Forum low shoes V5 Cloud White / Hazy Orange / Core Black - 10",
"manufacturerCode": "",
"unitPrice": 9400,
"quantity": 1,
"totalPrice": 9400,
"goodProducts": 1,
"reasonCode": "reasonAccidentalOrder",
"reason": "",
"condition": "New With Box",
"status": "Approved",
"dateSubmitted": "2021-10-15T18:11:33.488Z",
"type": "product",
"tax": 6.18,
"totalValue": 100.18
},
{
"id": "51945590-2de3-11ec-82ac-12444306e6c3",
"createdIn": "2021-10-15T18:11:33.9621775Z",
"refundId": "4fd9fab1-2de3-11ec-82ac-0a07788173f1",
"orderId": "1164033206599-01",
"userId": "3a1d2c0a-199c-4c98-bc72-ba8b2de0afa3",
"imageUrl": "https://sandboxusdev.vteximg.com.br/arquivos/ids/189101-55-55/White-and-Blue---10-1.jpg?v=637532549039470000",
"sku": "80008131",
"skuId": "Adidas01-White-10V5",
"productId": "80008068",
"ean": "A12345-10V5",
"brandId": "2000012",
"brandName": "AdidasV2",
"skuName": "Forum low shoes V5 White and Blue - 10",
"manufacturerCode": "",
"unitPrice": 9400,
"quantity": 1,
"totalPrice": 9400,
"goodProducts": 1,
"reasonCode": "reasonAccidentalOrder",
"reason": "",
"condition": "New With Box",
"status": "Approved",
"dateSubmitted": "2021-10-15T18:11:33.487Z",
"type": "product",
"tax": 6.18,
"totalValue": 100.18
}
],
"updatedRequest": {
"id": "4fd9fab1-2de3-11ec-82ac-0a07788173f1",
"createdIn": "2021-10-15T18:11:32.9614776Z",
"userId": "3a1d2c0a-199c-4c98-bc72-ba8b2de0afa3",
"orderId": "1164033206599-01",
"name": "arturo castillo",
"email": "[email protected]",
"phoneNumber": "+13475983586",
"country": "United States",
"locality": "Winter Garden",
"address": "Liki Tiki Village, 17777 Bali Blvd ",
"state": "FL",
"zip": "34787",
"totalPrice": 18800,
"paymentMethod": "card",
"extraComment": "",
"giftCardCode": "",
"giftCardId": "",
"refundedAmount": 20036,
"iban": "",
"accountHolder": "",
"status": "Approved",
"dateSubmitted": "2021-10-15T18:11:32.395Z",
"type": "request"
}
}
https://{accountName}.{environment}.com.br/no-cache/returns/api/change-product-status/{request_id}
Body Parameters:
Param | Type | Required | Default |
---|---|---|---|
skuId | string | yes, optional if refId is present |
|
refId | string | yes, optional if skuId is present |
|
goodQuantity | number | yes |
Info:
- If
refId
is present,skuId
will be ignored - If
goodQuantity
is 0, the product status will be "denied
". - If
goodQuantity
is lower than quantity from request, the product status will be "partially approved
". - If
goodQuantity
is equal with quantity from request, the product status will be "approved
".
{
"success": true,
"errorMessage": ""
}
https://{accountName}.{environment}.com.br/no-cache/returns/api/check-status/{request_id}
{
"success": true,
"status": "Pending verification",
"nextStatus": "Approved, Partially approved, Denied",
"requiredSteps": [
{
skuId: 'skuId',
skuRefId: 'sku refId',
name: 'Sku name',
info: "Verification required",
status: 'Current product status'
}
],
"errorMessage": ""
}
https://{accountName}.{environment}.com.br/no-cache/returns/api/update-status/{request_id}
Body Parameters:
Param | Type | Required | Default |
---|---|---|---|
submittedBy | string | yes | - |
{
"success": true,
"errorMessage": ""
}
Upcoming documentation: