v1

latestOpenAPI 3.0.02026-07-2475182625.5 KB

Returns

Create a return

Creates an order return request for full, partial, or combined refunds and returns processing details for each requested return.

Use the Examples dropdown in the Try It! panel to select a request body:

Example	Description
Full return	Submits a full refund for the specified order, returning 100% of its value without item‑level details.
Partial return	Issues a partial refund for the specified order, refunding only the listed items and amounts.
Combined return	Mixes modes: one order is fully refunded, while another gets a partial refund on specified items.

post/returns

Request body

Example request

{
  "returns": [
    {
      "order": "abCdE1FGH2Hij3KLMnOpqR",
      "reason": "DUPLICATE_ORDER",
      "note": "As requested by customer",
      "notification": "ORIGINAL",
      "refundType": "PARTIAL",
      "items": [
        {
          "product": "your-product-path-ID"
        }
      ]
    }
  ]
}

Response

Example response

{
  "returns": [
    {
      "return": "aBCDE12fGH3iJkL4mNOpqr",
      "reference": "ABC1234567-8910-11121D",
      "completed": true,
      "changed": 1731381500223,
      "changedValue": 1731381500223,
      "changedInSeconds": 1731381500,
      "changedDisplay": "11/12/24",
      "changedDisplayISO8601": "2024-11-12",
      "account": "abCdE1FGH2Hij3KLMnOpqR",
      "currency": "USD",
      "payoutCurrency": "USD",
      "totalReturn": 5,
      "totalReturnDisplay": "$5.00",
      "totalReturnInPayoutCurrency": 5,
      "totalReturnInPayoutCurrencyDisplay": "$5.00",
      "taxDisplay": "$0.00",
      "taxInPayoutCurrencyDisplay": "$0.00",
      "subtotal": 5,
      "subtotalDisplay": "$5.00",
      "subtotalInPayoutCurrency": 5,
      "subtotalInPayoutCurrencyDisplay": "$5.00",
      "totalRefundInPayoutCurrency": 5,
      "payment": {
        "type": "test",
        "cardEnding": "4242"
      },
      "reason": "Duplicate Order",
      "note": "As requested by customer",
      "type": "RETURN",
      "refundPerformerType": "api",
      "refundSourceComponent": "refund",
      "original": {
        "id": "AbC1D2eFGH34ijklmnopQrs",
        "order": "AbC1D2eFGH34ijklmnopQrs",
        "reference": "ABC123456-7891-01112",
        "account": "abCdE1FGH2Hij3KLMnOpqR",
        "currency": "USD",
        "payoutCurrency": "USD",
        "total": 10,
        "totalDisplay": "$10.00",
        "totalInPayoutCurrency": 10,
        "totalInPayoutCurrencyDisplay": "$10.00",
        "taxDisplay": "$0.00",
        "taxInPayoutCurrencyDisplay": "$0.00",
        "subtotal": 10,
        "subtotalDisplay": "$10.00",
        "subtotalInPayoutCurrency": 10,
        "subtotalInPayoutCurrencyDisplay": "$10.00",
        "notes": [],
        "tags": {
          "TagKey1": "test123",
          "TagKey2": "TagValue2"
        }
      },
      "customer": {
        "first": "Jane",
        "last": "Doe",
        "email": "jane.doe@example.com",
        "company": "Example Company",
        "phone": "5555551234",
        "subscribed": true
      },
      "items": [
        {
          "product": "furious-falcon",
          "display": "Furious Falcon",
          "sku": "sku-12345",
          "refundType": "Partial Refund",
          "subtotal": 5,
          "subtotalDisplay": "$5.00",
          "subtotalInPayoutCurrency": 5,
          "subtotalInPayoutCurrencyDisplay": "$5.00",
          "attributes": {
            "AttributeKey1": "AttributeValue1",
            "AttributeKey2": "AttributeValue2"
          }
        }
      ],
      "refundPerformer": "jane.doe@example.com",
      "action": "return.create",
      "result": "success"
    }
  ]
}