# Update Table of Offers Endpoint

**CRED-6186 - 2026-05-26**

## Endpoint

| Field | Value |
| --- | --- |
| Path | `/merchantRest/merchantSrv/update-table-of-offers` |
| Method | `POST` |
| App group | `mconnect` |
| Auth required | Yes |
| Auth modes | JWT |
| IP whitelist | Disabled |

## S3 Schema Paths

| Schema | Path |
| --- | --- |
| Route schema | `api-wrapper/JSON/ssejson.json` |

## Purpose

This endpoint allows an SSE merchant to securely select and update an applicant's loan offer directly from the Table of Offers. It updates the core database tables seamlessly through the JSON state machine (bypassing synchronous Laravel backend commands), constructs a dynamic history comment, and dispatches an asynchronous webhook back to the merchant along with triggering a document revision job.

## Request Headers

| Header | Required | Description |
| --- | --- | --- |
| `Host` | Yes | Used to resolve domain configuration |
| `Authorization` | Yes | Used for JWT route authentication |

## Request Body

```json
{
  "applicationLoanNo": "1234567890",
  "offer_id": "123_b"
}
```

## Validation

Documented from `paths./merchantRest/merchantSrv/update-table-of-offers.post.requestBody.content`:

- `applicationLoanNo`: **Required**. String. Must match an existing `loan_application_no` in `pro_forma_invoice`.
- `offer_id`: **Required**. String or Integer. May contain flow suffixes like `_b` (Bureau Surrogate Limit) or `_r` (Residual EMI).

## Execution Steps & Business Rules

This endpoint executes heavy SQL logic within its `execution` state machine to validate constraints and dynamically format the output.

| Condition / Step | Description | Error Response |
| --- | --- | --- |
| **Application Validation** | Fetches the `state` of the application. It MUST be IN `('waiting for decision', 'pre approved', 'cf approved', 'approved')`. | `CF300 / 201004` ("Auto update cannot be done because status is {state} and offer cannot be updated.") |
| **E-Sign Validation** | Queries `loan_hypothecation_model`. If `applicant_signing`, `co_applicant_signing`, or `first_party_signing` is true, the update is blocked. | `CF300 / 201005` ("Auto update cannot be done because E-sign agreement is done, please connect with CF advisor") |
| **Flow Detection** | Splits the `offer_id` string to identify the `tof_type` (`bureau_surrogate_limit`, `residual_emi`, or defaults to `minimum_tenure`). | - |
| **Amount Extraction** | Executes a `CASE WHEN` SQL query to extract the exact `loan_amount` and `emi` from either `loan_decision_table` or `loan_decision_approved_amount` depending on the `tof_type`. | - |
| **Dynamic Comment Gen** | Fetches previous states and offer configurations to execute a `CONCAT` query, constructing a highly detailed HTML comment comparing the previous and new offer amounts, ROIs, and EMIs. | - |

## Persistence

The `persistence` block directly applies these changes to the core application database:

| Table | Operation | Condition | Important fields |
| --- | --- | --- | --- |
| `consumer_application` | `UPDATE` | `id = $application_id` | Updates `offer_id` (raw int), `approved_amount`, `loan_amount`, and `emi`. |
| `consumer_application_emi_calculation` | `UPDATE` | `application_id = $application_id` | Updates `table_of_offers_logic` with the new flow type. |
| `consumer_application_emi_calculation_lock` | `DELETE` | `application_id = $application_id` | Deletes the lock so a fresh EMI schedule can be generated. |
| `comments` | `INSERT` | - | Inserts the dynamically generated HTML tracking comment. |
| `queue_log` | `INSERT` | `$webhook_row isNotNull` | Dispatches `command:mConnect` to instantly trigger the `Merchant-Comment` webhook. |
| `jobs` | `INSERT` | - | Dispatches the `reviseDocuments` job to regenerate the EMI schedule and PDF documents. |

## Responses

| `cf_code` | HTTP status | Return code | Meaning |
| --- | --- | --- | --- |
| `CF200` | 200 | `200` | Success / Offer Updated |
| `CF300` | 200 | `201002` | Validation failure (Missing offer_id) |
| `CF300` | 200 | `201003` | Validation failure (Loan Application Number Not Exist) |
| `CF300` | 200 | `201004` | Business failure (Invalid Application Status) |
| `CF300` | 200 | `201005` | Business failure (E-sign already completed) |
| `CF500` | 500 | `500` | Internal/SQL failure |

## Side Effects

- **Database updates:** Directly mutates the `consumer_application` amounts and EMI configurations.
- **Queue Jobs:** Directly queues a `reviseDocuments` job for the Laravel worker.
- **Webhooks:** Pushes to RabbitMQ to fire an immediate webhook back to the merchant via `mConnectWebhook`.