Settlements

Overview

The Settlements API is tailored for merchants to access and manage their settlement data efficiently. This API focuses on delivering settlement reports through an API-first approach, prioritizing ease and speed in accessing crucial financial information. This guide outlines the fundamental operations of the Settlements API and its applications. For a more detailed understanding, including parameters, request and response formats, and error handling, please refer our API reference.

How It Works

The Settlements API offers two distinct types of settlements:

  1. Detailed Settlements: This version aligns with what merchants receive in SFTP reports and when downloading settlement reports via the Merchant portal. It offers comprehensive data for each settlement event.
  2. Summarized Settlements: Displayed as a table in the Merchant portal's Settlements tab, this version provides a condensed view of settlement events, ideal for quick overviews.

List settlement events

Use the GetSettlementEvents and GetSettlementEventSummaries endpoints to retrieve settlements and settlement summaries for a specific merchant.

Query parameters

ParameterData TypeDescription
merchant_id
Required
stringThe Affirm Merchant ID.
limitintegerThe maximum number of results per page. Default is 5.
afterdateThe beginning of the date range (inclusive). Default is the beginning of time.
beforedateThe end of the date range (inclusive). Default is today.
from_cursor_uuidstringOptional paging cursor uuid after which results should be returned. Returned in prev_page.
from_cursor_datedateOptional paging cursor date after which results should be returned. Returned in prev_page.
to_cursor_uuidstringOptional paging cursor uuid before which results should be returned. Returned in next_page.
to_cursor_datedateOptional paging cursor date before which results should be returned. Returned in next_page.
orderingstringOptional parameter to define ordering of results. Default is descending chronological order.
  • GetSettlementEvents retrieves a list of settlement events for a specific merchant. This is useful for tracking individual settlement transactions.
  • GetSettlementEventsSummaries retrieves a list of settlement event summaries for a specific merchant.

Example Requests

curl --request GET \
     --url 'https://www.affirm.com/api/partner/v1/settlements/events?merchant_id=MERCHANT-ARI-1234&limit=10&after=2023-01-31&before=2023-05-30' \
     --header 'accept: application/json'
curl --request GET \
     --url 'https://www.affirm.com/api/partner/v1/settlements/daily?merchant_id=MERCHANT-ARI-1234&limit=10&after=2023-05-31' \
     --header 'accept: application/json'

Example Response

{
  "count": 10,
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "date": "2020-01-31",
      "effective_date": "2020-03-18T03:16:02Z",
      "purchase_id": "PURCHASE-ARI-123",
      "order_id": "A1B2C3D4",
      "transaction_event_id": "TRANSACTION-EVENT-123",
      "merchant_id": "MERCHANT-ARI-123",
      "event_type": "loan_capture",
      "sales": 12345,
      "refunds": -450,
      "fees": -30,
      "total_settled": 11865,
      "mdr": 0.05,
      "deposit_id": "DEPOSIT-ID-123",
      "currency": "USD",
      "attribute": "CORRECTION",
      "removal_state": "failed"
    }
  ],
  "prev_page": "example.com%2Fprev_date",
  "next_page": "example.com%2Fnext_date"
}
{
  "count": 10,
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "date": "2020-01-31",
      "deposit_id": "ABCDEFG",
      "total_sales": 12345,
      "total_refunds": -450,
      "total_fees": -30,
      "total_settled": 11865,
      "account_last_four": "1234",
      "currency": "USD",
      "removal_state": "failed",
      "error_code": "RO2",
      "error_message": "ACCOUNT_CLOSED",
      "error_timestamp": "string"
    }
  ],
  "prev_page": "example.com%2Fprev_date",
  "next_page": "example.com%2Fnext_date"
}