> 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/en/hackle-admin-api/admin-api/get-contracts-settlements.md).

# \[GET] Get Contract Settlement Information

{% hint style="info" %}
This feature is only supported on the Enterprise plan.
{% endhint %}

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

## Request

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

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

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

#### Terminology

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

#### 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.

<table><thead><tr><th width="196.04296875">Category</th><th width="199.59765625">Description</th><th>Included Events</th></tr></thead><tbody><tr><td>AB</td><td>A/B Test events</td><td>A/B Test experiment exposures</td></tr><tr><td>FF</td><td>Feature Flag events</td><td>Feature Flag feature exposures</td></tr><tr><td>RC</td><td>Remote Config events</td><td>Remote Config requests</td></tr><tr><td>CUSTOM_TRACK</td><td>Custom events</td><td>Custom events sent directly by the customer</td></tr><tr><td>SYSTEM_TRACK</td><td>Auto-collected events<br>(excluding CRM events)</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>Auto-collected events<br>(CRM events)</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>Data import events</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>List of contract settlement records</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>Contract group name</td></tr><tr><td>startDate</td><td>String(date)</td><td>X</td><td>Contract group start date</td></tr><tr><td>endDate</td><td>String(date)</td><td>X</td><td>Contract group end date</td></tr><tr><td>contracts</td><td>List(Contract)</td><td>X</td><td>List of contracts belonging to the contract group</td></tr><tr><td>settlement</td><td>Settlement</td><td>O</td><td>Settlement information</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>Contract name</td></tr><tr><td>startDate</td><td>string(date)</td><td>X</td><td>Contract start date</td></tr><tr><td>endDate</td><td>string(date)</td><td>X</td><td>Contract end date</td></tr><tr><td>originalAmount</td><td>BigDecimal</td><td>X</td><td>Contract amount<br>(amount on the contract)</td></tr><tr><td>priorDeductionAmount</td><td>BigDecimal</td><td>X</td><td>Prior deduction amount</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>Settlement reference date</td></tr><tr><td>totalCalculatedAmount</td><td>BigDecimal</td><td>X</td><td>Total calculated amount</td></tr><tr><td>totalSettledAmount</td><td>BigDecimal</td><td>X</td><td>Total actual settled amount</td></tr><tr><td>items</td><td>List(Settlement.item)</td><td>X</td><td>List of settlement details per workspace * event</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>Workspace name</td></tr><tr><td>eventCategoryName</td><td>String</td><td>X</td><td>Event category name</td></tr><tr><td>usageCount</td><td>Long</td><td>X</td><td>Usage (count)</td></tr><tr><td>unitPrice</td><td>BigDecimal</td><td>X</td><td>Per-event unit price</td></tr><tr><td>calculatedAmount</td><td>BigDecimal</td><td>X</td><td>Calculated amount<br>(usageCount * unitPrice)</td></tr><tr><td>deductionSource</td><td>String</td><td>X</td><td>Deduction source display name</td></tr><tr><td>settledAmount</td><td>BigDecimal</td><td>X</td><td>Actual settled amount (excluding free deductions)</td></tr><tr><td>startDate</td><td>string(date)</td><td>X</td><td>Settlement application start date</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

Returns a 400 status if the request information is invalid.

#### Response Body

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

### 401 Unauthorized

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

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

### 403 Forbidden

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

```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/en/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.