Sign in

v41

latestOpenAPI 3.0.0UNLICENSEDraw.githubusercontent.com2026-07-0839165177.6 KB
Test Helpers

Refund simulated return

Refund a simulated return using the order total as the simulated refund amount.

post/api/v1/test-helpers/returns/{returnId}/refund

Path parameters

returnIdstring required

Request body

costBearer'shopper' | 'developer' | 'rye'

Who absorbs the merchant-retained shortfall S on a return — the gap between what the merchant was charged and what it refunded (restocking fees, return shipping, partials). Selected per-developer via the refundCostBearingStrategy Hypertune flag and resolved into this enum by the durable-workers cost-policy adapter.

  • shopper (default): the shopper eats S. Both anchors reconstruct from the merchant refund, so a short merchant refund shrinks the shopper refund and developer credit in lockstep.
  • developer: the shopper is made whole at the original charge C; the developer's deposit is credited only what Rye recovered (the merchant anchor), so the developer absorbs S.
  • rye: the shopper is made whole at C and the developer's full drawdown debit D is restored, so Rye absorbs S.

Response

The refunded simulated return

updatedAtstring date-time required

When the Return record was last updated.

createdAtstring date-time required

When the Return record was created.

reason'defective' | 'wrong_item' | 'unwanted' | 'color' | 'not_as_described' | 'size_too_large' | 'size_too_small' | 'style' | 'other' required

Reason a shopper is returning an order, supplied on the create-return call: defective (arrived damaged or faulty), wrong_item (not what was ordered), unwanted (changed their mind), color / size_too_large / size_too_small / style (wrong color, size, or style), not_as_described (differs from the listing), and other (anything else).

checkoutIntentIdstring required

Rye checkout intent id that produced the order being returned.

orderIdstring required

Rye order id (order_<32 hex>) this Return was opened against.

state'requested' | 'requires_action' | 'processing' | 'refunded' | 'denied' | 'failed' required

Lifecycle state of a Return:

  • requested — submitted to the merchant, awaiting approval.
  • requires_action — approved; the shopper must ship the items back.
  • processing — approved and in flight (items shipped, or no shipping required), awaiting the refund.
  • refunded — terminal; the refund has been issued and reconciled.
  • denied — terminal; the merchant declined the return.
  • failed — terminal; the return could not be completed.
idstring required

Rye return id (ret_<32 hex>).

Example response

{
  "refunds": [
    {
      "shopperRefundTotal": {
        "currencyCode": "USD",
        "amountSubunits": 1500
      }
    }
  ]
}