Skip to main content
The Returns API lets you open a return against a completed order and follow it through to a refund. Returns are whole-order: you return the entire order rather than individual line items. Once created, a return progresses asynchronously toward the shopper’s refund.
The Returns API currently supports Shopify orders only. Support for additional marketplaces will be added over time.

​
Creating a return

Call POST /api/v1/returns with the Rye orderId and a reason (such as defective, wrong_item, or unwanted). The order must be completed.
curl
curl --request POST \
  --url https://api.rye.com/api/v1/returns \
  --header "Authorization: Bearer $RYE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{ "orderId": "order_8c2b…", "reason": "defective" }'
The response returns the new return’s id and its state. The reference has the full request and response shape.

​
Lifecycle

A return moves through the states below and ends in refunded, denied, or failed. The state field tells you where it is, and which details are present on the response (a shipping label, a denial reason, or the refund).

​
Following a return

Poll GET /api/v1/returns/{returnId} to track a return until it reaches a terminal state. Once it is refunded, the response reports the amount returned to the shopper.

​
Handling requires_action

When a return reaches requires_action, the shopper needs to ship the items back before the merchant will refund. The response carries a nextAction with a prepaid return label at nextAction.shipItemsToMerchant.label.url. Forward that URL to the shopper so they can print the label and send the items in. 
{
  "id": "ret_3f9a…",
  "state": "requires_action",
  "nextAction": {
    "type": "ship_items_to_merchant",
    "shipItemsToMerchant": {
      "label": { "url": "https://…/return-label.pdf" }
    }
  }
}
Once the shopper ships the items and the merchant issues the refund, the return advances to refunded on its own. No further calls are required. (When a merchant approves a return without needing the items back, nextAction.type is no_action_required and the return skips straight to processing.)
If the original order was paid from your drawdown balance, Rye credits that balance when it reconciles the refund. Orders paid by other methods refund the shopper’s own funds and don’t affect your balance.