---
title: "List returns"
method: GET
path: "/v1/returns"
tags: ["Returns"]
---

# List returns

`GET /v1/returns`

## Request

- Base URL: `https://api.augustus.com`
- URL: `https://api.augustus.com/v1/returns`
- Auth: HTTP bearer

Lists deposit returns for the merchant with cursor-based pagination.

## Query parameters

- `limit` integer
- `cursor` string
- `status` 'initiated' | 'submitted' | 'sent' | 'failed' | 'returned'
- `deposit_id` string, uuid
- `created_at.gte` string, date-time
- `created_at.lte` string, date-time

## Response `200`

Paginated list of returns

- ListReturnsResponseDto
  - `data` object[], required
    - `id` string, uuid, required: Unique identifier of the return.
    - `type` 'return', required: Resource type discriminator.
    - `status` 'initiated' | 'submitted' | 'sent' | 'failed' | 'returned', required: Current status of the return.
    - `deposit_id` string, uuid, required: ID of the parent deposit.
    - `amount` string, required: Amount as a string decimal (e.g. "100.50").
    - `currency` 'EUR' | 'GBP' | 'USD' | 'USDC', required: Currency code (ISO 4217 or crypto).
    - `failure` object, nullable, required: Failure details when status is failed, otherwise null.
      - `code` 'account_closed' | 'account_blocked' | 'insufficient_funds' | 'invalid_account_format' | 'invalid_routing_number' | 'invalid_instruction' | 'invalid_amount' | 'invalid_time' | 'duplicate_transaction' | 'payee_verification_failed' | 'system_error' | 'provider_system_error' | 'rejected_by_correspondent_bank' | 'blocked_by_review' | 'unknown', required: Failure code.
      - `message` string, required: Human-readable description of the failure.
      - `retry` boolean, required: Whether the return can be retried.
    - `initiated_at` string, date-time, required: ISO 8601 UTC timestamp when the return was initiated.
    - `sent_at` string, date-time, nullable, required: ISO 8601 UTC timestamp when the return was sent.
    - `tx_hash` string, nullable, required: Transaction hash for crypto returns, or null when not known. Only blockchain rails support this field.
    - `rail` 'sepa' | 'sepa_instant' | 'faster_payments' | 'swift' | 'internal' | 'target' | 'ach' | 'fedwire' | 'bitcoin' | 'bitcoin_testnet4' | 'ethereum' | 'ethereum_sepolia' | 'solana' | 'solana_devnet' | 'polygon' | 'polygon_amoy' | 'null', nullable, required: Payment scheme or blockchain used for the return, or null when unknown.
    - `metadata` object, required: Set of up to 50 key-value string pairs you can attach to store structured information, such as correlating this resource with an object in your own system. Keys may be up to 40 characters and values up to 500 characters.
  - `has_more` boolean, required
  - `next_cursor` string, nullable, required
  - `has_previous` boolean, required
  - `previous_cursor` string, nullable, required

## Changes

- **2026-10-16** `f7ded6c181ab`: 1 info
  - endpoint added
- **2026-08-26** `ca35cff0b637`: 1 warning, 1 info
  - added the new `submitted` enum value to the `data/items/status` response property for the response status `200`
  - added the new enum value `submitted` to the `query` request parameter `status`
- **2026-08-21** `79d607871de9`: 4 breaking, 3 warning, 8 info
  - removed the enum value `paid` from the `query` request parameter `status`
  - removed the enum value `pending` from the `query` request parameter `status`
  - removed the required property `data/items/created_at` from the response with the `200` status
  - removed the required property `data/items/updated_at` from the response with the `200` status
  - …11 more
- **2026-08-17** `3ed0a0aba68b`: 4 info
  - removed the `BTC` enum value from the `data/items/currency` response property for the response status `200`
  - removed the `ETH` enum value from the `data/items/currency` response property for the response status `200`
  - removed the `POL` enum value from the `data/items/currency` response property for the response status `200`
  - removed the `SOL` enum value from the `data/items/currency` response property for the response status `200`
- …earlier changes not shown

[Operation history](https://skmtc.dev/augustus/apis/ivy-api/changes/v1/returns/get.md)

---

[API](https://skmtc.dev/augustus/apis/ivy-api.md) - [All operations](https://skmtc.dev/augustus/apis/ivy-api/llms.txt) - [OpenAPI document](https://skmtc.dev/augustus/apis/ivy-api/revisions/e87bdcac11cc?raw)