Return App V3

Source code

⚠️ This app is no longer maintained by VTEX. This means support and maintenance are no longer provided.

The Return App allows merchants to enable customers to request a return for their items and to manage the Return Request Process in their store.

Features

Store: Returns

A specific section under My Account on each store. In this section, the customer can view the history, status, and details of their created returns. As well as creating a new Return Request.

Admin: Return Request List

In this section of the merchant's admin, merchants can view and manage all return requests created by their customers.

Admin: Return Settings

In this section of the merchant's admin, merchants control the conditions for allowing the return process for a given item or items per customer.

• Max Days: When an order creation date is older than the Max Days to return, the user won't be able to select that order for a return

• Terms and Conditions: link to the Terms and Conditions offered by the store. (not provided by the app)

• Excluded categories: List of categories to be excluded for the return process. Any item that belongs to any of these categories will not be allowed to be returned. The store user will see a message stating that the item is not allowed to be returned.

• Return Payment Options:

  -- Same as Order: Payment will be refunded to the same payment method used in the order. -- Automatically refund requests - Automatically refund any payment method when the configuration to refund is set to be the same as the order.

  -- Allowed to choose: customer will select any of the refund options selected by the store. Disclaimer: Requests that were set to refund via credit card trigger the automatic refund.

Disclaimer: For the cases that the return app creates a refund, the return invoice (invoice type input) will be created in the OMS with the return request id as the invoice number.

• Custom Return Reasons: Allows the store to define their own custom return reasons. This setting will overwrite the default reasons. The custom Return Reasons can be translated manually by the admin.

  Default return reason
  Accidental Order
  Better Price
  Performance
  Incompatible
  Item Damaged
  Missed Delivery
  Missing Parts
  Box Damaged
  Different Product
  Defective
  Arrived in addition
  No Longer Needed
  Unauthorized purchase
  Different from website

• Other Option: toggle this to include a generic other return request reason. The store user can input any generic value if this one is chosen.

• Allow PickUp Points: allow the customer to set a pickup point to drop off the items to return. It uses the geocoordinates from the order to find the closest pickup points.

• Proportional shipping value: the shipping value to be refunded per item will be automatically calculated based on the item value percentage of the total order value.

• Item condition selector: requires the store user to select the condition of the items

Transactional Emails

The app leverages VTEX Message Center to notify customers when a return request is created and when its status changes.

When creating a return request for the first time, the app creates a default template oms-return-request-confirmation_{locale} that is modifiable on the Message Center to suit each store's needs. The locale will be filled with the locale the store user had when browsing the store.

In addition to the confirmation template, upon successful update of the Return Request Status, the app also creates a oms-return-request-status-update_{locale}.

Both templates will always be created in English. It is the store's responsibility to translate them to the desired locale.

API

Create Return Request

To create a Return Request, make a POST request to the following endpoint: https://{accountName}.myvtex.com/_v/return-request with an example body in the form of:

{
"items": [{
"orderItemIndex": 0,
"quantity": 1,
"returnReason": {
"reason": "Wrong type"
},
"condition": "newWithBox"
}],
"orderId": "1240221188059-01",
"refundPaymentData": {
"refundPaymentMethod": "sameAsPurchase"
},
"pickupReturnData": {
"addressId:"",
"addressType": "CUSTOMER_ADDRESS",
"address": "Rua Haddock Lobo",
"city": "São Paulo",
"state": "SP",
"country": "Br",
"zipCode": "01403003"
},
"customerProfileData": {
"name": "Filadelfo Braz",
"email": "filadelfo.braz+test@gmail.com",
"phoneNumber": "123432122"
},
"userComment": "This is a test from API",
"locale": "pt-PT"
}

Field	Description	isRequired
orderId	string orderId to where the Return Request is being made to	true
items	array of individual itemObject to be returned	true
items orderItemIndex	integer Index of the item in the Order object from the OMS	true
items quantity	integer number to be returned for the given orderItemIndex	true
items condition	enum values: newWithBox, newWithoutBox, usedWithBox, usedWithoutBox	false
items returnReason	object with reason to return the item	true
items returnReason reason	string reason to return	true
items returnReason otherReason	string Description of the reason when it is otherReason	false
customerProfileData	object with customer information	true
customerProfileData name	string Customer name for the return request	true
customerProfileData email	string customer's email for the return request	true
customerProfileData phoneNumber	string customer's phone number for the return request	true
pickupReturnData	object with information where the items should be picked up	true
pickupReturnData addressId	string id of the customer's address can be an empty string	true
pickupReturnData address	stringcustomer address	true
pickupReturnData city	string city of the address	true
pickupReturnData country	string country of the address	true
pickupReturnData zipCode	string postal code of the address	true
pickupReturnData addressType	enum possible values: PICKUP_POINT, CUSTOMER_ADDRESS	true
refundPaymentData	object with refund information	true
refundPaymentData refundPaymentMethod	enum possible values: bank, card, giftCard, sameAsPurchase	true
refundPaymentData iban	stringrequired when refundPaymentMethod is set as bank	false
refundPaymentData accountHolderName	string required when refundPaymentMethod is set as bank	false
userComment	string comment to be added to the creation	false
locale	string locale for the customer to visualize the return	true

A successful creation of a Return Request should return a status 201 with a response in the form of:

{
"requestId": "requestId"
}

Update a Return Request Status

Make a PUT request to the following endpoint: https://{accountName}.myvtex.com/_v/return-request/{requestId} with the following example body:

{
"status":"packageVerified",
"comment":{
"value":"Test comment",
"visibleForCustomer": false
},
"refundData":{
"items":[{
"orderItemIndex":0,
"quantity":1,
"restockFee":12
}],
"refundedShippingValue":1
}
}

Field	Description	isRequired
status	enum possible values: new, processing, pickedUpFromClient,pendingVerification, packageVerified, amountRefunded, denied, cancelled	true
comment	object only required if not updating status	false
comment value	string only required if not updating status	true
comment visibleForCustomer	boolean the comment will be shown to the customer. Default false	false
refundData	object only considered when status sent is packagedVerified	false
refundData items	array of objects with items approved to be returned	true
refundData items orderItemIndex	integerIndex of the item in the Order object form the OMS	true
refundData items quantity	integer number to be returned for the given orderItemIndex	true
refundData items restockFee	integer discount to be applied to the amount to be refunded, can be zero	true
refundData refundedShippingValue	integer shipping amount to be refunded, can be zero	true

To update the request to the next possible status, one just needs to pass a payload with the key status and the status as its value. It's possible to send the comment payload with all the statuses. When sending the status packageVerified, the refundData object must be included.

The request can be denied up to the pickedUpFromClient status. After that, it's only possible to deny a request by passing quantity zero to all items when sending the packageVerified status.

When sending the status packageVerified, the next status will automatically be set to packageVerified or denied based on the information in refundData.items.

When sending the status amountRefunded, the app will refund the payment method if the store user paid the order with a credit card and selected to be refunded via credit card, or if the store forces refunds to the same method as the purchase.

Add comments without updating status To add a comment to a request, one only needs to send the payload with the status equal to the current one and pass the comment object.

Retrieve a Return Request

To get a Return Request, make a GET request to the following endpoint: https://{accountName}.myvtex.com/_v/return-request/{requestId}

Retrieve Return Request List

To retrieve a List of Return Requests, make a GET request to the following endpoint: https://{accountName}.myvtex.com/_v/return-request The search params available are:

• _page integer
• _perPage integer
• _status enum
• _sequenceNumber string
• _id string
• _dateSubmitted string e.g: _dateSubmitted=2022-06-12,2022-07-13
• _orderId string
• _userEmail string

By default, requests will only include a summary. If you want to get all the fields for the requests, you can pass another search parameter:

• _allFields string (any truthy value)

Customization

In order to apply CSS customizations in this and other blocks, follow the instructions given in the recipe on Using CSS Handles for store customization.

CSS Handles COMMON
'contactDetailsCommonContainer'
'currentRequestStatusContainer'
'itemDetailsListContainer'
'itemVerificationDeniedContainer'
'itemVerificationApprovedContainer'
'itemVerificationPartiallyContainer'
'itemVerificationNewContainer'
'commonPickupContainer'
'refundMethodDetailContainer'
'approvedValuesContainer'
'requestedValuesContainer'
'returnValuesContainer'
'totalContainer'
'totalWrapperContainer'
'statusHistoryContainer'
'jumpToPageContainer'
'listTableContainer'
'listTableFilterContainer'
'mobileReturnListContainer'
'controlGridVisibility'
'controlGridVisibilityButtons'
'emptyList'
'returnList'
'returnListSingle'
'returnListDouble'
'returnListItem'
'returnListItemHeader'
'returnListItemImage'
'returnListItemInfo'
'returnListItemInfoDate'
'returnListItemInfoIdContainer'
'returnListItemInfoStatus'

CSS Handles STORE
'contactPickupContainer'
'addressContainer'
'addressHeaderWrapper'
'pickupAddressTitle'
'tooltipToggleWrapper'
'addressInputContainer'
'cityInputContainer'
'stateInputContainer'
'zipCodeInputContainer'
'countryInputContainer'
'submitDetailsContainer'
'contactAddressWrapper'
'paymentCommentWrapper'
'confirmationActionsContainer'
'backButtonWrapper'
'submitButtonWrapper'
'confirmContactContainer'
'confirmContactTitle'
'confirmContactText'
'confirmPaymentContainer'
'confirmPaymentTitle'
'accountHolderWrapper'
'ibanWrapper'
'accountHolderText'
'confirmPaymentValue'
'ibanText'
'refundPaymentText'
'confirmPickupContainer'
'confirmPickupTitle'
'confirmPickupText'
'contactDetailsContainer'
'contactDetailsTitle'
'contactNameInputWrapper'
'contactEmailInputWrapper'
'contactPhoneInputWrapper'
'detailsRowContainer'
'detailsTdWrapper'
'productSectionWrapper'
'productText'
'productImageWrapper'
'productImage'
'itemsDetailText'
'itemsListContainer'
'itemsListTheadWrapper'
'paymentMethodContainer'
'paymentBankWrapper'
'pickupPointContainer'
'conditionDropdwonContainer'
'otherReasonOptionContainer'
'returnDetailsContainer'
'orderIdDetailsWrapper'
'creationDateDetailsWrapper'
'returnInfoTableContainer'
'returnInfoTheadContainer'
'returnInfoTableText'
'returnInfoBodyContainer'
'itemsListTheadWrapper'
'paymentMethodContainer'
'paymentBankWrapper'
'pickupPointContainer'
'conditionDropdwonContainer'
'otherReasonOptionContainer'
'returnDetailsContainer'
'orderIdDetailsWrapper'
'creationDateDetailsWrapper'
'returnInfoTableContainer'
'returnInfoTheadContainer'
'returnInfoTableText'
'returnInfoBodyContainer'
'returnInfoTrBodyWrapper'
'returnInfoBodyImgWrapper'
'returnInfoReasonConditionWrapper'
'termsAndConditionsContainer'
'termsAndConditionsLink'
'userCommentDetailsContainer'
'cardItemsWrapper'
'itemDetailsListWrapper'
'cardWrapper'
'statusWrapper'
'productImageWrapper'
'productImage'
'productDetailsWrapper'
'productNameWrapper'
'productName'
'productRefWrapper'
'productReasonWrapper'
'productConditionWrapper'
'productSellerWrapper'
'productQuantityWrapper'
'productSellingPriceWrapper'
'productTaxWrapper'
'productTotalWrapper'
'productKey'
'productValue'
'productText'
'quantityWrapper'
'quantityKey'
'quantityValue'
'availableToReturnWrapper'
'availableToReturnKey'
'availableToReturnValue'
'quantitySelectorWrapper'
'reasonWrapper'
'conditionWrapper'
'highlightedFormMessage'

Known issues

• When a store has a process to create return invoices (invoice type input) outside the return app, the app will consider those items, and they will not be able to be returned via the app. However, when an item is already committed in a return request and an invoice is created considering that item with an invoice number different than the return request ID, there will be more processed items to return than invoice items. It can be seen via the GraphQL query orderToReturnSummary.

• When installing the app in a workspace - or creating a new one - the app will not behave as expected. This is because the Master Data Builder does not automatically create a schema for that workspace. To fix that, one can just link the app in the workspace using the toolbelt. Doing so will create a new Master Data schema for that workspace, and the app should work fine.

  Workaround

  To avoid the issue with the Masterdata builder when installing a new version of the APP in the master environment, follow these steps:

  1. Create a PROD WS within the account where you will install the APP.
  2. Install the new version of the APP in this PROD workspace: vtex install vtex.return-app@3.x.x
  3. Create a DEV WS, and link the APP latest version to the workspace: vtex link
  4. Check if the documents are on the listing page of the PROD WS. /admin/returns/requests/
  5. If they are, then you are safe to install on the Master environment.

---

Documentation for v2 here.

v3 consists on a major change from v2, please do not refer to v2 documents for v3.