---
title: "Tutorial: Configuring returns and exchanges"
slug: "tutorial-configuring-returns-and-exchanges"
tags: ["config api", "platform", "exchange", "refund", "tutorial", "api", "omnichannel manager ", "return"]
updated: 2025-10-13T08:47:48Z
published: 2025-10-13T08:47:48Z
canonical: "docs.newstore.com/tutorial-configuring-returns-and-exchanges"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.newstore.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tutorial: Configuring returns and exchanges

## Returns

Here's how returns and exchanges work in NewStore:

1. Assign Customer, place normal order, pay with credit card.
2. Look at customer’s Activity screen and open previous order.
3. Apply return and inspect cart payload. Note the following:
  - All we must do is to create a return is to add `cart.returns` to the cart.
  - After the cart is synced, `cart.payments.potential_store_credit` is added. `potential_store_credit` is the total credit the customer has from the returned order.
4. Checkout and select `Refund to Original Payment Method`. Refunding to original payment method is the default refunding behavior, nothing needs to be set in the cart for choosing this option.
  - Because this is a return (no exchange), total refunded amount equals `cart.remainingAmount` which is the same as the amount in `potential_store_credit` payment.
  - Look at `cart.paymentStatuses`, note that `status` of `potential_store_credit` is `draft` because we never used this credit.
5. To get the refund method (where the money was refunded to), we need to make another API call to `/customer_orders/<returns[0].orderId>`.

On the response payload, we must correlate a payment `activity` in `paymentHistory` with `returnId` from cart. In this case the correlation is `paymentHistory[1].activities[0].correlationId === cart.returns[0].returnId`

### Returns: Questions and more

- Why is a payment called `potential_store_credit`?

Because the store credit hasn't been used yet, it refers to the total amount a customer can potentially use from this credit.
- How do `cart.ids` from the original order and the return order relate to each other?

`cart.id` of the original order correlates with `returns[*].orderId` of the return order.
- Why do we call `/customer_orders/` with `<returns[0].orderId>`?

Because `<returns[0].orderId>` contains the original payment methods along with the returns.
- Why are we getting the `orderId` from `returns[0]`? What if there is more than one?

All `returns[*]` belong to the same order, returns from different orders is currently not supported.
- Can we call the `/customer_orders/` endpoint with `cart.id` from the return order?

We won't find the information we need there, since refund methods are in the payment history of the original order.
- Is a new order being created when placing the return?

No, since we are not actually creating a new order, just returning from the original order.

## Exchanges

> [!NOTE]
> Important
> 
> Cross-country exchanges are not supported when the taxes or tax policies in the countries you are trying to exchange the item(s) in are different.
> 
> For example, if you buy an item online or in a store in Germany, and then go to a Swedish store to exchange the item, the transaction will be unsuccessful.

### Equal exchanges

1. Create an equal exchange order by returning a product and buying a product with the same price.
2. Look at `cart.payments`:
  - `paymentStatuses[...].status` for `store_credit` payment is `succeeded` because we successfully processed `store_credit` (we used the store credit to buy the new item).
  - We got a new property in the cart: `cart.exchange`, with information about this exchange checkout.

#### Equal Exchanges: Questions and more

1. Why are we calling `/customer_orders/` with `<returns[0].orderId>`?

Because `<returns[0].orderId>` contains the original payment methods along with the returns.

> [!TIP]
> Note
> 
> There are no payments in `paymentHistory` to correlate to this return. Why? Because customer didn’t get refunded.
2. Is a new order being created when placing the return?

Yes, the new order for the new product(s) bought.
3. Look at exchange and original orders in HQ
4. What payment information do we get when calling `customer_orders/` with `cart.id` from the original order?
  - Original payment and `store_credit` issued
5. What payment information we get when calling `customer_orders/` with `cart.id` from the return order?
  - `store_credit` redeemed (used to pay for exchanged product)

### Negative exchanges

1. Create negative exchange order by returning product and adding product with lower `price` to the cart. Inspect payload:
  - `cart.payments.potential_store_credit.amount` is equal to the total exchange credit available to the customer.
  - `cart.exchange.amount` is the total amount of the refund.
  - `remainingAmount` is equal to `cart.totals.grandTotal` minus payments amount.
2. Place cart and inspect cart payload again:
  - `store_credit` payment changed. Now it is equal to the total credit used for this checkout. Therefore, `remainingAmount` is now 0.
  - For exchanges, always use `cart.exchange` for determining balance amount.
3. Look at response payload from `/customer_orders/` and correlate `paymentHistory` activity with `returnId` to determine where the money was refunded.

#### Negative exchanges: Questions and more

1. Look at exchange and original orders in HQ.
2. Why does `store_credit` payment changes amounts?

It changes because customer didn't use the whole credit amount.
3. What payment information do we get when calling `customer_orders/` with `cart.id` from the original order?
  - Original payment
  - `store_credit` issued
  - Amount refunded to original payment method
4. What payment information we get when calling `customer_orders/` with `cart.id` from the return order?
  - `store_credit` redeemed (used to pay for exchanged product)

### Positive exchanges

1. Create a positive exchange order by returning a product and adding a product with higher price to the cart. Inspect `cart` payload (`payments`, `paymentStatuses`, `returnStatus`, `exchange`).
2. Place cart, inspect `cart` payload:
  - Look at `cart.payments`: new payment and `store_credit` payments are there.
  - Look at `cart.paymentStatuses` to check that all `statuses` are `succeeded`. Note that `payments` ids correlate with `paymentStatuses` ids.
  - Look at `cart.returnStatus` to check that returns `succeeded`
  - Look at `cart.exchange` to get type and balance information on the exchange.

**Related topics**

- [Configuring exchanges as a payment strategy](/v1/docs/configuring-payment-providers#configuring-exchanges-as-a-payment-strategy)
- [Configuring exchanges as a payment strategy](/v1/docs/configuring-payment-providers#configuring-exchanges-as-a-payment-strategy)
- [Placing orders](/v1/docs/placing-orders#shopping-api)