[GET] Get Contract Settlement Information

This feature is only supported on the Enterprise plan.

Retrieves settlement information for contracts that are active as of the requested time.

Request

GET https://admin-api.hackle.io/v1/contracts/settlements

Authentication is performed using X-HACKLE-ADMIN-API-KEY. You must send this key as an HTTP header.

X-HACKLE-ADMIN-API-KEY: {X-HACKLE-ADMIN-API-KEY}

Example

curl -i -X GET \
  'https://admin-api.hackle.io/v1/contracts/settlements' \
  -H 'X-HACKLE-ADMIN-API-KEY: X-HACKLE-ADMIN-API-KEY_HERE' \
  -H 'Content-Type: application/json'

---

Response

200 OK

Returns a 200 response with query results for a successful request.

Terminology

Term	Description
Contract Group (ContractGroup)	A unit that bundles one or more contracts. When different contracts fall within the same period, they are managed at the contract group level.
Contract (Contract)	A unit corresponding to an actual contract document. It has a contract amount (originalAmount). Multiple workspaces can be mapped to a single contract.
Prior deduction amount (priorDeductionAmount)	An amount deducted in advance from the contract amount for reasons unrelated to the current settlement. Carryover of overage from a previous contract Cash top-up for CRM usage, etc. A negative value means the balance from a previous contract has been carried over, so the available amount exceeds the contract amount.
Settlement (Settlement)	A usage-based settlement snapshot generated daily. Usage and amounts are calculated for each combination of workspace and event category.
Calculated amount (calculatedAmount)	An amount computed as usage * unit price. It refers to the original amount before free deductions such as credits and promotions.
Actual settled amount (settledAmount)	The amount actually settled after applying deduction benefits such as credits and promotions.
Deduction source (deductionSource)	Indicates where the amount of the settlement item is deducted from. There are various sources, such as the contract itself, credits, and promotions.

Event Categories

Settlement aggregates usage by event category. Event categories serve as the basis for distinguishing the per-event unit price, and different unit prices apply depending on the category. The meaning of each category is as follows.

Category	Description	Included Events
AB	A/B Test events	A/B Test experiment exposures
FF	Feature Flag events	Feature Flag feature exposures
RC	Remote Config events	Remote Config requests
CUSTOM_TRACK	Custom events	Custom events sent directly by the customer
SYSTEM_TRACK	Auto-collected events (excluding CRM events)	https://docs.hackle.io/event-management/hackle-event
CRM_SYSTEM_TRACK	Auto-collected events (CRM events)	https://docs.hackle.io/event-management/hackle-event
IMPORT	Data import events

Response Body

Field	Type	Nullable	Description
contractGroupSettlements	List(ContractGroupSettlement)	X	List of contract settlement records

ContractGroupSettlement

Field	Type	Nullable	Description
contractGroupName	String	X	Contract group name
startDate	String(date)	X	Contract group start date
endDate	String(date)	X	Contract group end date
contracts	List(Contract)	X	List of contracts belonging to the contract group
settlement	Settlement	O	Settlement information

Contract

Field	Type	Nullable	Description
contractName	String	X	Contract name
startDate	string(date)	X	Contract start date
endDate	string(date)	X	Contract end date
originalAmount	BigDecimal	X	Contract amount (amount on the contract)
priorDeductionAmount	BigDecimal	X	Prior deduction amount

Settlement

Field	Type	Nullable	Description
snapshotDate	string(date)	X	Settlement reference date
totalCalculatedAmount	BigDecimal	X	Total calculated amount
totalSettledAmount	BigDecimal	X	Total actual settled amount
items	List(Settlement.item)	X	List of settlement details per workspace * event

Settlement.item

Field	Type	Nullable	Description
workspaceName	String	X	Workspace name
eventCategoryName	String	X	Event category name
usageCount	Long	X	Usage (count)
unitPrice	BigDecimal	X	Per-event unit price
calculatedAmount	BigDecimal	X	Calculated amount (usageCount * unitPrice)
deductionSource	String	X	Deduction source display name
settledAmount	BigDecimal	X	Actual settled amount (excluding free deductions)
startDate	string(date)	X	Settlement application start date

Example

{
  "contractGroupSettlements": [
    {
      "contractGroupName": "핵클_2026년 계약",
      "startDate": "2026-01-01",
      "endDate": "2026-12-31",
      "contracts": [
        {
          "contractName": "2026년 계약",
          "startDate": "2026-01-01",
          "endDate": "2026-12-31",
          "originalAmount": 50000000.0,
          "priorDeductionAmount": 5000000.0
        }
      ],
      "settlement": {
        "snapshotDate": "2026-06-29",
        "totalCalculatedAmount": 12000000.0,
        "totalSettledAmount": 7000000.0,
        "items": [
          {
            "workspaceName": "핵클 워크스페이스",
            "eventCategoryName": "AB",
            "usageCount": 5000000,
            "unitPrice": 0.12,
            "calculatedAmount": 600000.0,
            "deductionSource": "2026년 계약_크레딧_3,000,000원",
            "settledAmount": 0.0,
            "startDate": "2026-01-01"
          },
          {
            "workspaceName": "핵클 워크스페이스",
            "eventCategoryName": "FF",
            "usageCount": 8000000,
            "unitPrice": 0.05,
            "calculatedAmount": 400000.0,
            "deductionSource": "2026년 계약_프로모션_5,000,000원",
            "settledAmount": 0.0,
            "startDate": "2026-01-01"
          },
          {
            "workspaceName": "핵클 워크스페이스",
            "eventCategoryName": "CUSTOM_TRACK",
            "usageCount": 50000000,
            "unitPrice": 0.12,
            "calculatedAmount": 6000000.0,
            "deductionSource": "2026년 계약",
            "settledAmount": 6000000.0,
            "startDate": "2026-01-01"
          },
          {
            "workspaceName": "핵클 워크스페이스",
            "eventCategoryName": "SYSTEM_TRACK",
            "usageCount": 50000000,
            "unitPrice": 0.1,
            "calculatedAmount": 5000000.0,
            "deductionSource": "2026년 계약",
            "settledAmount": 1000000.0,
            "startDate": "2026-01-01"
          }
        ]
      }
    }
  ]
}

400 Bad Request

Returns a 400 status if the request information is invalid.

Response Body

{
    "code": "BAD_REQUEST",
    "message": "Bad Request"
}

401 Unauthorized

Returns a 401 status if the X-HACKLE-ADMIN-API-KEY header is missing or invalid.

{
    "code": "UNAUTHORIZED",
    "message": "Unauthorized"
}

403 Forbidden

Returns a 403 status if the API is called without the required permissions.

{
    "code": "FORBIDDEN",
    "message": "Forbidden"
}