> For the complete documentation index, see [llms.txt](https://docs.hackle.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hackle.io/hackle-admin-api/admin-api/get-contracts-settlements.md).

# \[GET] 계약 정산 정보 조회 API

{% hint style="info" %}
엔터프라이즈 플랜에서만 지원하는 기능입니다.
{% endhint %}

요청하신 시점을 기준으로 활성화된 계약에 관하여 정산 정보를 조회합니다.

## Request

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

**X-HACKLE-ADMIN-API-KEY**를 통해 인증을 진행합니다.\
해당 키를 HTTP 헤더로 전송해야 합니다.

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

#### Example

```bash
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

성공적인 요청인 경우 200 응답과 조회 결과를 반환합니다.

#### 용어 설명

<table><thead><tr><th width="225.0078125">용어</th><th width="534.8671875">설명</th></tr></thead><tbody><tr><td>계약 그룹 (ContractGroup)</td><td>하나 이상의 계약을 묶는 단위입니다.<br>같은 기간 안에 서로 다른 계약이 묶이는 경우 계약 그룹 단위로 관리됩니다.</td></tr><tr><td>계약 (Contract)</td><td>실제 계약서에 대응하는 단위입니다.<br>계약 금액(originalAmount)이 설정되어 있습니다.<br>하나의 계약에 여러 워크스페이스가 매핑될 수 있습니다.</td></tr><tr><td>선차감 금액(priorDeductionAmount)</td><td><p>현재 정산과 무관한 사유로 계약 금액에서 미리 차감된 금액입니다.</p><ul><li>이전 계약의 초과 사용분 이월</li><li>CRM 사용을 위한 캐시 충전 등</li></ul><p>음수인 경우 이전 계약의 잔액이 이월되어 사용 가능 금액이 계약 금액보다 많은 상태를 의미합니다.</p></td></tr><tr><td>정산 (Settlement)</td><td>일 단위로 생성되는 사용량 기반 정산 스냅샷입니다.<br>각 워크스페이스와 이벤트 카테고리 조합별로 사용량과 금액이 계산됩니다.</td></tr><tr><td>계산 금액 (calculatedAmount)</td><td>사용량 * 단가로 산출된 금액입니다.<br>크레딧, 프로모션 등 무료 차감 전 원래 금액을 의미합니다.</td></tr><tr><td>실 정산 금액 (settledAmount)</td><td>크레딧, 프로모션 등 차감 혜택을 적용한 후 실제로 정산되는 금액입니다.</td></tr><tr><td>차감 출처 (deductionSource)</td><td>해당 정산 항목의 금액이 어디서 차감되는지를 나타냅니다.<br>계약 자체, 크레딧, 프로모션 등 다양한 출처가 있습니다.</td></tr></tbody></table>

#### 이벤트 카테고리

정산은 이벤트 카테고리별 사용량을 집계합니다. 이벤트 카테고리는 건당 단가를 구분하는 기준이 되며, 카테고리에 따라 서로 다른 단가가 적용됩니다. 각 카테고리의 의미는 다음과 같습니다.

<table><thead><tr><th width="196.04296875">카테고리</th><th width="199.59765625">설명</th><th>포함 이벤트</th></tr></thead><tbody><tr><td>AB</td><td>A/B 테스트 이벤트</td><td>A/B 테스트 실험 노출</td></tr><tr><td>FF</td><td>기능플래그 이벤트</td><td>기능 플래그 기능 노출</td></tr><tr><td>RC</td><td>원격 구성 이벤트</td><td>원격구성 요청</td></tr><tr><td>CUSTOM_TRACK</td><td>사용자 정의 이벤트</td><td>고객이 직접 전송하는 사용자 정의 이벤트</td></tr><tr><td>SYSTEM_TRACK</td><td>자동 수집 이벤트<br>(CRM 제외 이벤트)</td><td><a href="https://docs.hackle.io/event-management/hackle-event">https://docs.hackle.io/event-management/hackle-event</a></td></tr><tr><td>CRM_SYSTEM_TRACK</td><td>자동수집 이벤트<br>(CRM 이벤트)</td><td><a href="https://docs.hackle.io/event-management/hackle-event">https://docs.hackle.io/event-management/hackle-event</a></td></tr><tr><td>IMPORT</td><td>데이터 import 이벤트</td><td></td></tr></tbody></table>

#### Response Body

<table><thead><tr><th width="225.0078125">Field</th><th width="254.75">Type</th><th width="101.38671875">Nullable</th><th>Description</th></tr></thead><tbody><tr><td>contractGroupSettlements</td><td>List(ContractGroupSettlement)</td><td>X</td><td>계약 정산 내역 리스트</td></tr></tbody></table>

**ContractGroupSettlement**

<table><thead><tr><th width="195.5703125">Field</th><th width="167.1953125">Type</th><th width="110">Nullable</th><th>Description</th></tr></thead><tbody><tr><td>contractGroupName</td><td>String</td><td>X</td><td>계약 그룹명</td></tr><tr><td>startDate</td><td>String(date)</td><td>X</td><td>계약 그룹 시작일</td></tr><tr><td>endDate</td><td>String(date)</td><td>X</td><td>계약 그룹 종료일</td></tr><tr><td>contracts</td><td>List(Contract)</td><td>X</td><td>계약 그룹에 속한 계약 목록</td></tr><tr><td>settlement</td><td>Settlement</td><td>O</td><td>정산 정보</td></tr></tbody></table>

**Contract**

<table><thead><tr><th width="195.5703125">Field</th><th width="167.1953125">Type</th><th width="110">Nullable</th><th>Description</th></tr></thead><tbody><tr><td>contractName</td><td>String</td><td>X</td><td>계약명</td></tr><tr><td>startDate</td><td>string(date)</td><td>X</td><td>계약 시작일</td></tr><tr><td>endDate</td><td>string(date)</td><td>X</td><td>계약 종료일</td></tr><tr><td>originalAmount</td><td>BigDecimal</td><td>X</td><td>계약 금액<br>(계약서상 금액)</td></tr><tr><td>priorDeductionAmount</td><td>BigDecimal</td><td>X</td><td>선차감 금액</td></tr></tbody></table>

**Settlement**

<table><thead><tr><th width="195.5703125">Field</th><th width="183.84375">Type</th><th width="103.94140625">Nullable</th><th>Description</th></tr></thead><tbody><tr><td>snapshotDate</td><td>string(date)</td><td>X</td><td>정산 기준일</td></tr><tr><td>totalCalculatedAmount</td><td>BigDecimal</td><td>X</td><td>전체 계산 금액 합계</td></tr><tr><td>totalSettledAmount</td><td>BigDecimal</td><td>X</td><td>실 정산 금액 합계</td></tr><tr><td>items</td><td>List(Settlement.item)</td><td>X</td><td>워크스페이스 * 이벤트 별 정산 상세 목록</td></tr></tbody></table>

**Settlement.item**

<table><thead><tr><th width="195.5703125">Field</th><th width="167.1953125">Type</th><th width="110">Nullable</th><th>Description</th></tr></thead><tbody><tr><td>workspaceName</td><td>String</td><td>X</td><td>워크스페이스 이름</td></tr><tr><td>eventCategoryName</td><td>String</td><td>X</td><td>이벤트 카테고리명</td></tr><tr><td>usageCount</td><td>Long</td><td>X</td><td>사용량 (건수)</td></tr><tr><td>unitPrice</td><td>BigDecimal</td><td>X</td><td>건당 단가</td></tr><tr><td>calculatedAmount</td><td>BigDecimal</td><td>X</td><td>계산 금액<br>(usageCount * unitPrice)</td></tr><tr><td>deductionSource</td><td>String</td><td>X</td><td>차감 출처 표시명</td></tr><tr><td>settledAmount</td><td>BigDecimal</td><td>X</td><td>실 정산 금액 (무료 차감 제외)</td></tr><tr><td>startDate</td><td>string(date)</td><td>X</td><td>정산 적용 시작일</td></tr></tbody></table>

#### Example

```json
{
  "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

유효하지 않은 요청 정보인 경우 400 상태를 반환합니다.

#### Response Body

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

### 401 Unauthorized

`X-HACKLE-ADMIN-API-KEY` 헤더값이 없거나 유효하지 않은 키인 경우 401 상태를 반환합니다.

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

### 403 Forbidden

권한이 없는 API를 호출할 경우 403 상태를 반환합니다.

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.hackle.io/hackle-admin-api/admin-api/get-contracts-settlements.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.