> ## Documentation Index
> Fetch the complete documentation index at: https://dvaultdocs.dukka.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tier API

> Manage account tiers and limits

# Tier API Documentation

## Overview

The Tier API provides endpoints for managing account tiers in the wallet service. It supports creating and updating tiers with daily and monthly transaction limits, and retrieving tier information.

## Base URL

`/api/v1/tiers`

## Authentication

All endpoints require authentication using an API key in the request headers:

* `X-API-KEY`: Your API key

## Endpoints

### Register Tier

Create a new tier configuration.

**Endpoint:** `POST /register`

**Headers:**

* `X-API-KEY`: API key for authentication

**Request Body:**

```json theme={null}
{
  "name": "string",
  "dailyLimit": "number",
  "monthlyLimit": "number",
  "tenantId": "string"
}
```

**Response:**

```json theme={null}
{
  "statusCode": 200,
  "message": "string",
  "data": {
    "id": "number",
    "name": "string",
    "tierId": "string",
    "dailyLimit": "number",
    "monthlyLimit": "number",
    "tenantId": "string",
    "createdAt": "string",
    "updatedAt": "string"
  }
}
```

### Update Tier

Update an existing tier configuration.

**Endpoint:** `POST /update/{tierId}`

**Headers:**

* `X-API-KEY`: API key for authentication

**Path Parameters:**

* `tierId`: The ID of the tier to update

**Request Body:**

```json theme={null}
{
  "name": "string",
  "dailyLimit": "number",
  "monthlyLimit": "number",
  "tenantId": "string"
}
```

**Response:**

```json theme={null}
{
  "statusCode": 200,
  "message": "string",
  "data": {
    "id": "number",
    "name": "string",
    "tierId": "string",
    "dailyLimit": "number",
    "monthlyLimit": "number",
    "tenantId": "string",
    "createdAt": "string",
    "updatedAt": "string"
  }
}
```

### View Tiers

Retrieve tiers with filtering and pagination.

**Endpoint:** `GET /get`

**Headers:**

* `X-API-KEY`: API key for authentication

**Query Parameters:**

* `name`: Tier name
* `tierId`: Tier ID
* `dailyLimit`: Daily transaction limit
* `monthlyLimit`: Monthly transaction limit
* `tenantId`: Tenant ID
* `page`: Page number (default: 0)
* `size`: Page size (default: 20)
* `sort`: Sort field and direction (e.g., "createdAt,desc")

**Response:**

```json theme={null}
{
  "statusCode": 200,
  "message": "string",
  "data": {
    "content": [
      {
        "id": "number",
        "name": "string",
        "tierId": "string",
        "dailyLimit": "number",
        "monthlyLimit": "number",
        "tenantId": "string",
        "createdAt": "string",
        "updatedAt": "string"
      }
    ],
    "pageable": {
      "pageNumber": "number",
      "pageSize": "number",
      "sort": {
        "sorted": "boolean",
        "unsorted": "boolean",
        "empty": "boolean"
      },
      "offset": "number",
      "paged": "boolean",
      "unpaged": "boolean"
    },
    "totalElements": "number",
    "totalPages": "number",
    "last": "boolean",
    "size": "number",
    "number": "number",
    "sort": {
      "sorted": "boolean",
      "unsorted": "boolean",
      "empty": "boolean"
    },
    "numberOfElements": "number",
    "first": "boolean",
    "empty": "boolean"
  }
}
```

## Error Responses

**401 Unauthorized**

```json theme={null}
{
  "statusCode": 401,
  "message": "user not authenticated",
  "data": null
}
```

**404 Not Found**

```json theme={null}
{
  "statusCode": 404,
  "message": "tier not found",
  "data": null
}
```

**409 Conflict**

```json theme={null}
{
  "statusCode": 409,
  "message": "tier already exists",
  "data": null
}
```

## Notes

* Tier Configuration:
  * Each tier has a unique name per tenant
  * Tiers have daily and monthly transaction limits
  * Tiers are associated with a specific tenant
* Tier Limits:
  * Daily limit: Maximum transaction amount per day
  * Monthly limit: Maximum transaction amount per month
  * Limits are enforced per account
  * Limits are checked before each transaction
* Tier Validation:
  * Duplicate tier names are prevented per tenant
  * Limits must be positive numbers
  * Tier name is required
  * Tenant ID is required
* Tier Permissions:
  * Tenant admins can manage their tiers
  * Platform admins can manage all tiers
  * Regular users cannot manage tiers
* Tier Tracking:
  * All tier changes are logged
  * Tier history is maintained
  * Limit violations are monitored
  * Failed operations are tracked
* Tier Notifications:
  * Tier creation is notified
  * Tier updates are logged
  * Limit violations are reported
  * Status changes are notified
* Tier Usage:
  * Tiers are assigned to accounts
  * Multiple accounts can use the same tier
  * Tier changes affect all associated accounts
  * Tier limits are enforced in real-time
* Tier Management:
  * Tiers can be updated at any time
  * Updates affect future transactions only
  * Existing transactions are not affected
  * Tier changes require admin approval