---
updatedAt: 2026-08-17T16:30:44.000Z
---

Fetch the complete documentation index at: https://docs.affirm.com/developers/llms.txt. Use this file to discover all available pages before exploring further. Append .md to any documentation page URL to get its markdown version.

# List Settlement Events

Lists settlement events by merchant.

> 📘 New Optional Response Fields for Universal Financing Parity Merchants (UFP)
>
> New *optional* response fields have been added for UFP merchants. The new fields include the following:
>
> * `initiating_merchant_id`: contains the ID of the merchant where order was made.
> * `city`: contains the store’s city where the order was made, obtained directly from card rails (externally controlled).
> * `store`: contains the store’s name where the order was made, obtained directly from card rails (externally controlled).
> * `card_last_four`: contains the last four digits of the payment instrument (FPAN).
> * `original_loan_amount`: contains the original order total.
> * `channel`: contains the channel type where an Affirm checkout was initiated, for example:
>
> ```
>       - Affirm Direct
>       - Apple Pay
>       - Google Pay
>       - Affirm Card
>       - Affirm VCN
> ```

# OpenAPI definition

```json
{
  "openapi": "3.0.0",
  "info": {
    "title": "Merchant Transaction API",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://sandbox.affirm.com/api/v1"
    },
    {
      "url": "https://api.affirm.com/api/v1"
    }
  ],
  "security": [
    {
      "basicAuth": []
    }
  ],
  "paths": {
    "/settlements/events": {
      "get": {
        "tags": [
          "Transactions API"
        ],
        "summary": "List Settlement Events",
        "description": "Lists settlement events by merchant.",
        "operationId": "list_settlement_events",
        "parameters": [
          {
            "name": "merchant_id",
            "in": "query",
            "description": "The Affirm Merchant ID",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "The maximum number of results per page. Default is 5.",
            "required": false,
            "schema": {
              "maximum": 1000,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "name": "after",
            "in": "query",
            "description": "The beginning of the date range (inclusive). Default is 30 days ago.",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "before",
            "in": "query",
            "description": "The end of the date range (inclusive)",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "from_cursor_uuid",
            "in": "query",
            "description": "Optional paging cursor uuid after which results should be returned. This uuid, along with from_cursor_date is returned in the prev_page field in the 200 response",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "from_cursor_date",
            "in": "query",
            "description": "Optional paging cursor date after which results should be returned. This date, along with from_cursor_uuid is returned in the prev_page field in the 200 response",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "to_cursor_uuid",
            "in": "query",
            "description": "Optional paging cursor uuid before which results should be returned. This uuid, along with to_cursor_date is returned in the next_page field in the 200 response",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "to_cursor_date",
            "in": "query",
            "description": "Optional paging cursor date before which results should be returned. This date, along with to_cursor_uuid is returned in the next_page field in the 200 response",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "ordering",
            "in": "query",
            "description": "Optional parameter to define ordering of results. Default is descending chronological order",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "ascending",
                "descending"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "HTTP 200 OK",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/PaginatedSettlementEventResponse"
                }
              }
            }
          },
          "400": {
            "description": "HTTP 400 Bad Request",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBadRequest"
                }
              }
            }
          },
          "401": {
            "description": "HTTP 401 Unauthorized",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorUnauthorized"
                }
              }
            }
          },
          "404": {
            "description": "HTTP 404 Not Found",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorNotFound"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerError"
                }
              }
            }
          },
          "503": {
            "description": "Unexpected Error",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/UnexpectedError"
                }
              }
            }
          }
        },
        "x-swagger-router-controller": "affirm.http.api.merchant.transaction.v1.api"
      }
    }
  },
  "components": {
    "schemas": {
      "ErrorBadRequest": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string",
            "description": "The error message.",
            "example": "Bad Request"
          },
          "status_code": {
            "type": "integer",
            "description": "The HTTP status code.",
            "example": 400
          },
          "type": {
            "type": "string",
            "description": "The error type.",
            "example": "BAD_REQUEST"
          },
          "code": {
            "type": "string",
            "description": "The error type.",
            "example": "BAD_REQUEST"
          }
        }
      },
      "ErrorNotFound": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string",
            "description": "The error message.",
            "example": "Not Found"
          },
          "status_code": {
            "type": "integer",
            "description": "The HTTP status code.",
            "example": 404
          },
          "type": {
            "type": "string",
            "description": "The error type.",
            "example": "NOT_FOUND"
          },
          "code": {
            "type": "string",
            "description": "The error type.",
            "example": "NOT_FOUND"
          }
        }
      },
      "ErrorUnauthorized": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string",
            "description": "The error message.",
            "example": "Unauthorized"
          },
          "status_code": {
            "type": "integer",
            "description": "The HTTP status code.",
            "example": 401
          },
          "type": {
            "type": "string",
            "description": "The error type.",
            "example": "UNAUTHORIZED"
          },
          "code": {
            "type": "string",
            "description": "The error type.",
            "example": "UNAUTHORIZED"
          }
        }
      },
      "InternalServerError": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "enum": [
              "internal_server_error"
            ]
          },
          "message": {
            "type": "string",
            "description": "Human readable message with details about the error"
          }
        }
      },
      "UnexpectedError": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string"
          },
          "message": {
            "type": "string",
            "description": "Human readable message with details about the error"
          }
        }
      },
      "SettlementEvent": {
        "required": [
          "currency",
          "date",
          "deposit_id",
          "effective_date",
          "event_type",
          "fees",
          "id",
          "merchant_id",
          "purchase_id",
          "refunds",
          "sales",
          "total_settled"
        ],
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique UUID for the settlement event",
            "example": "123e4567-e89b-12d3-a456-426614174000"
          },
          "date": {
            "type": "string",
            "description": "The disbursed date, which is the date that the deposit was initiated.",
            "format": "date"
          },
          "effective_date": {
            "type": "string",
            "description": "The date of the loan event that caused this Settlement.",
            "format": "date"
          },
          "purchase_id": {
            "type": "string",
            "description": "The ID of the purchase.",
            "example": "PURCHASE-ARI-123"
          },
          "order_id": {
            "type": "string",
            "description": "The Partner Order ID.",
            "example": "order_125"
          },
          "transaction_event_id": {
            "type": "string",
            "description": "The ID of the transaction event that caused the disbursement.",
            "example": "TRANSACTION-EVENT-123"
          },
          "merchant_id": {
            "type": "string",
            "description": "The ID of the merchant.",
            "example": "MERCHANT-ARI-123"
          },
          "event_type": {
            "type": "string",
            "description": "Type of settlement event.",
            "example": "loan_capture",
            "enum": [
              "dispute_opened",
              "dispute_resolved",
              "fee_adjustment",
              "loan_capture",
              "loan_refund",
              "merchant_fee",
              "partial_void",
              "refund_voided",
              "split_capture",
              "vcn_balance_adjustment"
            ]
          },
          "sales": {
            "type": "integer",
            "description": "The amount of the disbursement (before fees), in cents.",
            "example": 12345
          },
          "refunds": {
            "type": "integer",
            "description": "The amount of the refund (before fees), in cents.",
            "example": -12345
          },
          "fees": {
            "type": "integer",
            "description": "The fee amount (in cents).",
            "example": 12345
          },
          "transaction_fees": {
            "type": "integer",
            "description": "The transaction fee amount (in cents).",
            "example": 12345
          },
          "total_settled": {
            "type": "integer",
            "description": "The sale or refund amount net the fees (in cents).",
            "example": 12345
          },
          "mdr": {
            "type": "number",
            "description": "Merchant discount rate (merchant fee) associated with the charge.",
            "example": 0.05
          },
          "deposit_id": {
            "type": "string",
            "description": "The ACH identifier of the deposit made in the merchants bank account",
            "example": "DEPOSIT-ID-123"
          },
          "currency": {
            "type": "string",
            "description": "The currency of the settlement event",
            "example": "USD"
          },
          "attribute": {
            "type": "string",
            "description": "Returns \"CORRECTION\" if the settlement is a correction",
            "enum": [
              "CORRECTION"
            ]
          },
          "removal_state": {
            "type": "string",
            "description": "Returns the reason for removal, if the settlement had been removed.\n  * `failed` - The settlement had failed\n  * `rejected` - The settlement was rejected from the disbursements pipeline\n",
            "enum": [
              "failed",
              "rejected"
            ]
          },
          "transaction_id": {
            "type": "string",
            "description": "The ID of the transaction.",
            "example": "TRANSACTIONID123"
          },
          "initiating_merchant_id": {
            "type": "string",
            "description": "Optional response field received by UFP merchants and contains the ID of the merchant where order was made.",
            "example": "23e4567-e89b-12d3-a456-426614174000"
          },
          "city": {
            "type": "string",
            "description": "Optional response field received by UFP merchants and contains the store’s city where the order was made, obtained directly from card rails (externally controlled).",
            "example": "San Francisco"
          },
          "store": {
            "type": "string",
            "description": "Optional response field received by UFP merchants and contains the store’s name where the order was made, obtained directly from card rails (externally controlled).",
            "example": "The Clothing Store"
          },
          "card_last_four": {
            "type": "string",
            "description": "Optional response field received by UFP merchants and contains the last four digits of the payment instrument (FPAN).",
            "example": "1234"
          },
          "original_loan_amount": {
            "type": "integer",
            "description": "Optional response field received by UFP merchants and contains the original order total.",
            "example": 50000
          },
          "channel": {
            "type": "string",
            "description": "Optional response field received by UFP merchants and contains the channel type where an Affirm checkout was initiated.",
            "example": "Apple Pay",
            "enum": [
              "Affirm Direct",
              "Apple Pay",
              "Google Pay",
              "Affirm Card",
              "Affirm VCN"
            ]
          }
        }
      },
      "PaginatedSettlementEventResponse": {
        "required": [
          "count",
          "data",
          "next_page",
          "prev_page"
        ],
        "type": "object",
        "properties": {
          "count": {
            "type": "integer",
            "description": "The number of settlement events returned on the current page.",
            "example": 10
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SettlementEvent"
            }
          },
          "prev_page": {
            "type": "string",
            "description": "URL-encoded parameters that include the date and UUID of the previous results for cursor-based pagination. Empty string if no previous results. Previous results refer to newer results if sorted in descending chronological order, and will refer to older results if sorted in ascending chronological order.",
            "example": "example.com%2Fprev_page"
          },
          "next_page": {
            "type": "string",
            "description": "URL-encoded parameters that include the date and UUID of the next results for cursor-based pagination. Empty string if no next results. Next results refer to older results if sorted in descending chronological order, and will refer to newer results if sorted in ascending chronological order.",
            "example": "example.com%2Fnext_page"
          }
        }
      }
    },
    "securitySchemes": {
      "basicAuth": {
        "type": "http",
        "scheme": "basic"
      }
    }
  },
  "x-readme": {
    "explorer-enabled": true,
    "proxy-enabled": true,
    "samples-enabled": true
  }
}
```

# Sibling pages

* [List Transactions](https://docs.affirm.com/developers/reference/list_transactions.md)
* [Authorize Transaction](https://docs.affirm.com/developers/reference/authorize_transaction.md)
* [List Transaction Events](https://docs.affirm.com/developers/reference/list_transaction_events.md)
* [Read Transaction](https://docs.affirm.com/developers/reference/read_transaction.md)
* [Update Transaction](https://docs.affirm.com/developers/reference/update_transaction.md)
* [Capture Transaction](https://docs.affirm.com/developers/reference/capture_transaction.md)
* [Refund Transaction](https://docs.affirm.com/developers/reference/refund_transaction.md)
* [Void Transaction](https://docs.affirm.com/developers/reference/void_transaction.md)
* [List Settlement Event Summaries](https://docs.affirm.com/developers/reference/list_settlement_event_summaries.md)