Skip to main content

Tutorial: Returns and exchanges

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

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.

    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