Skip to main content
POST
/
api
/
v1
/
returns
JavaScript
import CheckoutIntents from 'checkout-intents';

const client = new CheckoutIntents({
  apiKey: process.env['CHECKOUT_INTENTS_API_KEY'], // This is the default and can be omitted
});

const _return = await client.returns.create({ orderId: 'orderId', reason: 'defective' });

console.log(_return.id);
{
  "updatedAt": "2023-11-07T05:31:56Z",
  "createdAt": "2023-11-07T05:31:56Z",
  "timeline": {
    "requestedAt": "2023-11-07T05:31:56Z",
    "failedAt": "2023-11-07T05:31:56Z",
    "deniedAt": "2023-11-07T05:31:56Z",
    "refundedAt": "2023-11-07T05:31:56Z",
    "refundIssuedAt": "2023-11-07T05:31:56Z",
    "returnApprovedAt": "2023-11-07T05:31:56Z"
  },
  "checkoutIntentId": "<string>",
  "orderId": "<string>",
  "id": "<string>",
  "refunds": [
    {
      "shopperRefundTotal": {
        "currencyCode": "USD",
        "amountSubunits": 1500
      },
      "refundedAt": "2023-11-07T05:31:56Z",
      "id": "<string>"
    }
  ],
  "failure": {
    "message": "<string>"
  },
  "denial": {
    "note": "<string>"
  },
  "nextAction": {
    "shipItemsToMerchant": {
      "label": {
        "url": "<string>"
      }
    }
  }
}

Authorizations

​
Authorization
string
header
required

Rye API key

Body

application/json

Request body for POST /api/v1/returns. Whole-order returns only — server enumerates the order's line items at create time.

​
reason
enum<string>
required

Reason for the return.

Available options:
defective,
wrong_item,
unwanted,
color,
not_as_described,
size_too_large,
size_too_small,
style,
other
​
orderId
string
required

Rye order id (order_<32 hex>) of the order being returned.

Response

Created

A single Return record. The state discriminator tells you which of denial, failure, and refunds is populated; nextAction is set once the Return is approved (see {@link NextActionResponse}).

​
updatedAt
string<date-time>
required

When the Return record was last updated.

​
createdAt
string<date-time>
required

When the Return record was created.

​
timeline
object
required

Per-transition timestamps; later stamps fill in as the Return advances.

​
reason
enum<string>
required

Reason the return was requested, echoed back from the create call.

Available options:
defective,
wrong_item,
unwanted,
color,
not_as_described,
size_too_large,
size_too_small,
style,
other
​
checkoutIntentId
string
required

Rye checkout intent id that produced the order being returned.

​
orderId
string
required

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

​
state
enum<string>
required

Lifecycle state; the discriminator for the optional sub-objects below.

Available options:
requested,
requires_action,
processing,
refunded,
denied,
failed
​
id
string
required

Rye return id (ret_<32 hex>).

​
refunds
object[]

Issued refunds. Present only on refunded.

​
failure
object

What went wrong. Present only on failed.

​
denial
object

Why the merchant declined the return. Present only on denied.

​
nextAction
object

What the shopper must do next (e.g. ship the items back). Present once the return is approved — i.e. on requires_action, processing, and refunded — and may be present on denied / failed if they were approved before terminating. Absent on requested.