# Manage SMS Costs

#### **Overview**

This API manages SMS costs at multiple levels: **TukuPay (default system-wide)**, **App Owner**, **Specific Customer**, and **Direct Customers**. If a customer-specific cost is not defined, the system falls back to the **default customer cost**.

***

**1. Add or Update SMS Costs**

* **Method:** `POST`
* **URL:** `/api/sms-costs`

**Request Body:**

```json
{
  "level": "SpecificCustomer",
  "pricePerSms": 0.7,
  "customerId": "cust123",
  "appId": null,
  "reason": "Custom pricing for high-volume customer",
  "effectiveFrom": "2024-12-13T00:00:00Z",
  "createdBy": "admin123"
}
```

**Request Body Fields:**

| **Field**       | **Type**   | **Required** | **Description**                                                                    |
| --------------- | ---------- | ------------ | ---------------------------------------------------------------------------------- |
| `level`         | `string`   | Yes          | The level of cost: `TukuPay`, `AppOwner`, `SpecificCustomer`, or `DirectCustomer`. |
| `pricePerSms`   | `number`   | Yes          | The cost per SMS in KES. For `TukuPay`, this is the default system-wide cost.      |
| `customerId`    | `string`   | Conditional  | Required for `SpecificCustomer`.                                                   |
| `appId`         | `string`   | Conditional  | Required for `AppOwner` level.                                                     |
| `reason`        | `string`   | Conditional  | Optional for all but required for internal or customer-specific costs.             |
| `effectiveFrom` | `datetime` | Yes          | When this cost becomes effective.                                                  |
| `createdBy`     | `string`   | Yes          | The user who set the cost.                                                         |

**Key Points:**

1. If `level` is `SpecificCustomer`, the `customerId` field must be provided.
2. If no cost exists for a specific customer, the system will use the **default customer cost** set under the `DirectCustomer` level.

**Example for Default Customer Cost:**

```json
{
  "level": "DirectCustomer",
  "pricePerSms": 0.8,
  "appId": null,
  "reason": "Default customer cost",
  "effectiveFrom": "2024-12-13T00:00:00Z",
  "createdBy": "admin123"
}
```

**Example for Specific Customer Cost:**

```json
{
  "level": "SpecificCustomer",
  "pricePerSms": 0.7,
  "customerId": "cust456",
  "reason": "Discount for high-volume usage",
  "effectiveFrom": "2024-12-13T00:00:00Z",
  "createdBy": "admin123"
}
```

***

**2. Retrieve Current SMS Costs**

* **Method:** `GET`
* **URL:** `/api/sms-costs/current`

**Query Parameters:**

| **Field**    | **Type** | **Required** | **Description**                                                                    |
| ------------ | -------- | ------------ | ---------------------------------------------------------------------------------- |
| `level`      | `string` | Yes          | The level of cost: `TukuPay`, `AppOwner`, `SpecificCustomer`, or `DirectCustomer`. |
| `appId`      | `string` | Conditional  | Required for `AppOwner`.                                                           |
| `customerId` | `string` | Conditional  | Required for `SpecificCustomer`.                                                   |

**Response Example (Specific Customer Cost):**

```json
{
  "level": "SpecificCustomer",
  "pricePerSms": 0.7,
  "customerId": "cust123",
  "effectiveFrom": "2024-12-13T00:00:00Z"
}
```

**Response Example (Default Customer Cost):**

```json
{
  "level": "DirectCustomer",
  "pricePerSms": 0.8,
  "effectiveFrom": "2024-12-13T00:00:00Z"
}
```

***

**3. List Historical SMS Costs**

* **Method:** `GET`
* **URL:** `/api/sms-costs/history`

**Query Parameters:**

| **Field**    | **Type** | **Required** | **Description**                                                                    |
| ------------ | -------- | ------------ | ---------------------------------------------------------------------------------- |
| `level`      | `string` | Yes          | The level of cost: `TukuPay`, `AppOwner`, `SpecificCustomer`, or `DirectCustomer`. |
| `appId`      | `string` | Conditional  | Required for `AppOwner`.                                                           |
| `customerId` | `string` | Conditional  | Required for `SpecificCustomer`.                                                   |

**Response Example:**

```json
[
  {
    "costId": "cost001",
    "level": "DirectCustomer",
    "pricePerSms": 0.8,
    "effectiveFrom": "2024-11-01T00:00:00Z",
    "createdBy": "admin123"
  },
  {
    "costId": "cost002",
    "level": "SpecificCustomer",
    "pricePerSms": 0.7,
    "customerId": "cust123",
    "effectiveFrom": "2024-12-01T00:00:00Z",
    "createdBy": "user456"
  }
]
```

***

#### **Implementation Notes**

1. **Default Costs:** The system always uses `DirectCustomer` costs as the fallback when no `SpecificCustomer` cost is found.
2. **Cost Hierarchy:**
   * `SpecificCustomer` overrides `DirectCustomer` for a particular customer.
   * `AppOwner` costs apply for app-based reselling.
   * `TukuPay` costs define the default for the entire system.
3. **Validation:** Ensure costs are correctly associated with the appropriate level and entity (e.g., `customerId` or `appId`).