If a customer receives a product and decides they do not want it, they can return the product to the merchant and receive a refund. The Rye API supports Returns are governed by the merchant’s store policies, so some of the

If the order has not shipped yet, you might be able to cancel it by using the cancelOrder mutation.

Key points

  • Rye APIs support product returns.
  • Return policies are set by the merchant who sold the product.
  • Returns occur after the product has shipped to the shopper.
    • If you want to cancel an order before it ships, you can request a refund for Amazon orders.
  • Webhooks are fired throughout the returns process, to keep you informed.

By marketplace


The returnOrder mutation can be used to initiate a return for an Amazon order.

After calling the endpoint developers can listen to webhook events to get updates on the return status and shipping label data. If Amazon approves the return, a RETURN_APPROVED webhook will be fired. This webhook contains a shippingLabelUrl field, which you should send the shopper to so they can proceed with returning the item. Returns can also be listed from Order.returns field, which is returned from queries like orderByID.

In general, the workflow looks like this:

  1. Developer calls returnOrder
  2. Rye fires a RETURN_REQUESTED webhook event.
  3. If the return is approved, Rye fires a RETURN_APPROVED webhook event.
    • On this event there is a shippingLabelUrl field. You should send the shopper to this URL so they can print the shipping label and return the item.
    • After the return is finalized, Rye fires a RETURN_CLOSED webhook event.
  4. If the return is declined, Rye fires a RETURN_DENIED webhook event.


If you are using a mix of Sell Anything and Sync API products it is recommended to use a single email for all orders otherwise you will not know when a shopper requests a return which means Rye would not be able to initiate a refund to the shopper.

Make sure the email resembles a person’s email and not a group email (e.g. john.doe@rye.com instead of orders@rye.com). Using a group email could trip Shopify’s fraud detection algorithm and cause your order to fail. If you signed up with Rye using a group email you can contact us via Slack or email support@rye.com and we can setup an email that would be forwarded to your group email.

Via Sell Anything API

In general, Rye is the merchant of record for the shopper in this case. Before we can issue a refund to the shopper, the following must happen:

  1. Developer will send the return request to the merchant.
  2. Once the request for return has been accepted or denied the developer will need to forward the information to the end shopper.
    • This includes any shipping information or labels that the shopper will need to return the item.
  3. Once the return has been completed, the developer should forward the information to Rye to process the refund.

Via Shopify app

The Shopify merchant is generally the merchant of record for the shopper in this case. This means that the shopper will need to work directly with the Shopify merchant for returns. Once the return is processed by the merchant, one of the following will happen depending on your billing agreement with us.

In general, Rye will refund the customer and close out the order request. If you are billed by invoice, the returned order will appear on your next invoice as a credit.