Skip to content

[return-app] EDU-17233 - Deprecated app callout #227

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
barbara-celi merged 4 commits into from
Feb 19, 2026
Merged

[return-app] EDU-17233 - Deprecated app callout #227

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
4a5eda1
Update README.md
barbara-celi Feb 2, 2026
dc60f38
Update CHANGELOG.md
barbara-celi Feb 2, 2026
eebdfbf
Update CHANGELOG.md
barbara-celi Feb 2, 2026
9ce5fcd
Improve wording and grammar in README.md
carolinamenezes Feb 12, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,9 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.

## [Unreleased]

### Fixed
- Updating README.

## [3.11.0] - 2024-12-13

### Added
Expand Down
68 changes: 32 additions & 36 deletions docs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,36 +1,32 @@
# Return App V3

## ⚠️ Maintenance ⚠️
*Starting June 1st 2023, this application will no longer be maintained by VTEX.*
[<i class="fa-brands fa-github"></i> Source code](https://github.com/vtex-apps/return-app)

---

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

The **Return App** gives merchants the option to allow customers to request a return for their items and it gives them the ability to manage the Return Request Process on their store.
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.
Here a customer will be able to visualize the history, status and details of their created returns. As well as creating a new **Return Request**.
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 are capable of visualizing and managing all the return requests created by their customers.
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 what are the conditions of allowing the return process for a given item or items per customer.
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, 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 that item is not allowed to be returned.
- **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 same as 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.
Expand All @@ -57,26 +53,26 @@ In this section of the merchant's admin, merchants control what are the conditio
|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 pick up point to drop off the items to return. It uses the geocoordinates from the order to find the closest pickup points.
- **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**: require the store user to select the condition of the items
- **Item condition selector**: requires the store user to select the condition of the items

### Transactional Emails

The app leverages the capabilites of VTEX Message Center to notify the customers when a return request is created and when the status of their return changes.
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 needs.
the locale will be filled with the locale the store user had when browsing the store.
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.

Additional to the confirmation template, on successful Return Request Status update, the app also creates a `oms-return-request-status-update_{locale}`.
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 responsability of the store to translate them to the desired 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:
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:

Expand Down Expand Up @@ -117,7 +113,7 @@ with an example body in the form of:
| ------------------------------------- | --------------------------------------------------------------------- | ---------- |
| 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 form the OMS | 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 |
Expand All @@ -128,7 +124,7 @@ with an example body in the form of:
| 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 empty string | true |
| pickupReturnData addressId | `string` id of the customer's address can be an empty string | true |
| pickupReturnData address | `string`customer address | true |
| pickupReturnData city | `string` city of the address | true |
| pickupReturnData country | `string` country of the address | true |
Expand Down Expand Up @@ -187,25 +183,25 @@ with the following example body:
| 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 status. When sending the status packageVerified it's necessary to send the refundData object.
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 status packageVerified.
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 be automatically set to packageVerified or denied based on the information inside refundData.items.
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 when the store user paid the order using credit card, and has selected to be refunded via credit card or the store forces refunds in the same method as the purchase.
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, ones only needs to send the payload with status equals to the current one and pass the comment object.
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:
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:
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:

Expand All @@ -218,7 +214,7 @@ The search params available are:
- \_orderId `string`
- \_userEmail `string`

By default, the requests will only have a summary of the request. If you want to get all the fields for the requests, you can pass another search param:
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)

Expand Down Expand Up @@ -371,15 +367,15 @@ In order to apply CSS customizations in this and other blocks, follow the instru

## Known issues

- When a store has a process to create return invoices ([invoice type input](https://developers.vtex.com/vtex-rest-api/reference/invoicenotification)) 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 a invoice number different than the return request id, there will be more processed items to return then invoices items - It can be seen using the query `orderToReturnSummary` on GraphQL.
- When a store has a process to create return invoices ([invoice type input](https://developers.vtex.com/vtex-rest-api/reference/invoicenotification)) 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 behavior as expected. This is due to the masterdata builder not creating a schema for that workspace automatically. To fix that, one can just link the app in the workspace using the toolbelt. Doing so, there will be a new masterdata schema related to that workspace and the app should work fine.
- 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:
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 you will install the APP.
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/`
Expand Down
Loading