---
title: "Create Return"
method: POST
path: "/returns"
---

# Create Return

`POST /returns`

## Request

- Base URL: `https://app.moderntreasury.com/api`
- URL: `https://app.moderntreasury.com/api/returns`
- Auth: HTTP basic

## Request body

- object
  - `returnable_id` string, required: The ID of the object being returned.
  - `returnable_type` string, required: The type of object being returned. Currently, this may only be `incoming_payment_detail`.
  - `code` string: For ACH returns, this is the required ACH return code. Refer to [the guide](doc:originating-an-ach-return) on originating ACH returns for a full list of acceptable codes.
  - `reason` string: An optional description of the reason for the return. This is for internal usage and will not be transmitted to the bank.
  - `date_of_death` string, date: If the return code is R14 or R15, a date of death must be provided.
  - `additional_information` string: If provided, this string will populate the addenda information field of the ACH addenda record. Only the first 44 characters of this string will be used. Any additional characters will be truncated.
  - `ledger_transaction` object: Specifies a [ledger transaction](ref:ledger-transaction-object) object that will be created with the return. If the ledger transaction cannot be created, then the return creation will fail. The resulting ledger transaction will mirror the status of the return. See [Linking to other Modern Treasury objects](doc:linking-to-other-modern-treasury-objects).
    - `description` string: An optional free-form description for internal use. Maximum of 1000 characters allowed.
    - `metadata` string, json: Metadata to be added to the ledger transaction. Must be a JSON object.
    - `effective_at` string, date-time: Format: ISO8601 to 6 decimal places. Defaults to time of insertion in the DB if not provided
    - `ledger_entries` object[]
      - `amount` integer, required: Supports any int value up to 10³⁶.
      - `direction` string, required: One of `credit` or `debit`.
      - `ledger_account_id` string, required
      - `lock_version` integer: Lock version of the ledger account. This can be passed when creating a ledger transaction to only succeed if no ledger transactions have posted since the given version. See [this guide](https://docs.moderntreasury.com/docs/handling-concurrency#using-the-lock_version-field) for more details. This will trigger synchronous processing, which imposes an additional rate limit on the API. See [Synchronous Ledger Entry Rate Limiting](https://docs.moderntreasury.com/docs/synchronous-ledger-entry-rate-limiting) for details.
      - `pending_balance_amount` object: Use "gt" (>), "gte" (>=), "'lt" (<), "lte" (<=), or "eq" (=) to lock on the account’s pending balance. If any of these conditions would be false after the transaction is created, the entire call will fail with error code 422. See [this guide](https://docs.moderntreasury.com/docs/handling-concurrency#locking-on-account-balance) for more details. This will trigger synchronous processing, which imposes an additional rate limit on the API. See [Synchronous Ledger Entry Rate Limiting](https://docs.moderntreasury.com/docs/synchronous-ledger-entry-rate-limiting) for details.
        - `lt` integer
        - `lte` integer
        - `eq` integer
        - `gte` integer
        - `gt` integer
        - `not_eq` integer
      - `posted_balance_amount` object: Use "gt" (>), "gte" (>=), "'lt" (<), "lte" (<=), or "eq" (=) to lock on the account’s posted balance. If any of these conditions would be false after the transaction is created, the entire call will fail with error code 422. See [this guide](https://docs.moderntreasury.com/docs/handling-concurrency#locking-on-account-balance) for more details. This will trigger synchronous processing, which imposes an additional rate limit on the API. See [Synchronous Ledger Entry Rate Limiting](https://docs.moderntreasury.com/docs/synchronous-ledger-entry-rate-limiting) for details.
        - `lt` integer
        - `lte` integer
        - `eq` integer
        - `gte` integer
        - `gt` integer
        - `not_eq` integer
      - `available_balance_amount` object: Use "gt" (>), "gte" (>=), "'lt" (<), "lte" (<=), or "eq" (=) to lock on the account’s available balance. If any of these conditions would be false after the transaction is created, the entire call will fail with error code 422. See [this guide](https://docs.moderntreasury.com/docs/handling-concurrency#locking-on-account-balance) for more details. This will trigger synchronous processing, which imposes an additional rate limit on the API. See [Synchronous Ledger Entry Rate Limiting](https://docs.moderntreasury.com/docs/synchronous-ledger-entry-rate-limiting) for details.
        - `lt` integer
        - `lte` integer
        - `eq` integer
        - `gte` integer
        - `gt` integer
        - `not_eq` integer
      - `show_resulting_ledger_account_balances` boolean: If true, response will include the balance of the associated ledger account for the entry and will trigger synchronous processing, which imposes an additional rate limit on the API. See [Synchronous Ledger Entry Rate Limiting](https://docs.moderntreasury.com/docs/synchronous-ledger-entry-rate-limiting) for details.
      - `metadata` string, json

---

[API](https://skmtc.dev/modern-treasury/apis/modern-treasury-api-byob.md) - [All operations](https://skmtc.dev/modern-treasury/apis/modern-treasury-api-byob/llms.txt) - [OpenAPI document](https://skmtc.dev/modern-treasury/apis/modern-treasury-api-byob/revisions/1f24e1f6b3fb?raw)