Skip to content

khrizzcristian/return-app

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

275 Commits
admin
admin
 
 
common
common
 
 
docs
docs
 
 
messages
messages
 
 
node
node
 
 
pages
pages
 
 
react
react
 
 
store
store
 
 
.eslintignore
.eslintignore
 
 
.eslintrc
.eslintrc
 
 
.gitignore
.gitignore
 
 
.prettierrc
.prettierrc
 
 
CHANGELOG.MD
CHANGELOG.MD
 
 
crowdin.yml
crowdin.yml
 
 
debug.log
debug.log
 
 
manifest.json
manifest.json
 
 
package.json
package.json
 
 
yarn.lock
yarn.lock
 
 

Repository files navigation

Return App

VTEX Return App

Installation Guide

  • Open the VTEX App Store and install this app on your store, or run the following command on VTEX toolbelt:

vtex install vtex.return-app@1.x

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

Settings

  • 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
    • Excluded categories: Products that are in those categories will not be eligible for return
    • Payment 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

Short description

The return application serves the necessary functionalities for requesting returns from customers, and their processing by the administrators of the online store.

Installation and configuration

The application can be installed using the following command in VTEX Toolbelt: vtex install vtex.return-app@0.x

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

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.

Routes:

The application use 6 routes. 3 routes for admins and 3 for customers

Admin routes:

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

Customer routes:

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

Return requests information

Available payment methods

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

Request statuses

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

API

Get requests list

Generic badge 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 -
Response body example:
[
    {
        "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": "customer_email@domain.com",
            "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": "customer_email@domain.com",
            "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": []
    }
]

Get request by id

Generic badge https://{accountName}.{environment}.com.br/no-cache/returns/api/get-request/{request_id}

Response body example:
{
    "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": "customer_email@domain.com",
            "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": []
    }
}

Add comment

Generic badge 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
}

Set restock fee and shipping value to refund

Generic badge 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
}
Response body example:
{
    "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": "arturo@vinneren.com.mx",
        "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"
    }
}

Change product status

Generic badge 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".
Response body example:
{
    "success": true,
    "errorMessage": ""
}

Check request status

Generic badge https://{accountName}.{environment}.com.br/no-cache/returns/api/check-status/{request_id}

Response body example:
{
    "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": ""
}

Update request status

Generic badge https://{accountName}.{environment}.com.br/no-cache/returns/api/update-status/{request_id}

Body Parameters:

Param Type Required Default
submittedBy string yes -
Response body example:
{
    "success": true,
    "errorMessage": ""
}

Upcoming documentation:

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

1 star

Watchers

0 watching

Forks

15 forks
Report repository

Releases

2 tags

Packages

No packages published

Contributors 14

Languages