Manage SMS Costs

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 t

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:

{
  "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:

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

Example for Specific Customer Cost:

{
  "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):

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

Response Example (Default Customer Cost):

{
  "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:

[
  {
    "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).