Saving Goals

The Saving Goals module enables creation of savings targets (Hajj, emergency fund, etc.) with periodic auto-deduction from a source account into a dedicated holding account per goal. Endpoints are split across two controllers: SavingGoalsController at /saving-goals for CRUD + manual deduction, and OrgSavingGoalController for organization-level statistics summaries. Each goal has an owner_type (INDIVIDUAL/ORGANIZATION/MORIA), a lifecycle status, and a liquidity_type flag (loose vs locked).

Property	Value
Base URL	`{HOST}/v1`
Auth	Bearer JWT (header `Authorization`) or cookie `access_token`
Content-Type	`application/json`
Error envelope	`{ "message": string \| string[], "statusCode": number, "error": string }`
Validation	Global `ValidationPipe` · `whitelist: true`, `forbidNonWhitelisted: true` · unknown field → 400
Related modules	accounts, users, organizations, investments (convert-goals), withdrawal
Document version	v1 · 2026-05-20
Audience	Internal FE devs (mobile + web)

Summary

FE creates a saving goal via POST /saving-goals — the service automatically creates a separate holding account (Architecture B). Users can pause, update parameters, run a manual deduction when auto-deduction fails, and delete the goal. Organization/MORIA admins can read aggregate summaries via GET /summary/saving-goals.

Method	Path	Summary
POST	`/v1/saving-goals`	Create a new saving goal (auto-creates a holding account)
GET	`/v1/saving-goals`	Paginated list of saving goals with status/liquidity/type filters
GET	`/v1/saving-goals/:id`	Detail of a single saving goal
PATCH	`/v1/saving-goals/:id`	Update goal parameters (name, target, deduction, etc.)
PATCH	`/v1/saving-goals/:id/pause`	Pause/unpause auto-deduction
PATCH	`/v1/saving-goals/:id/manual-deduction`	Manual deduction (recovery when auto fails)
DELETE	`/v1/saving-goals/:id`	Delete a saving goal
GET	`/v1/summary/saving-goals`	Organization statistics summary (admin / MORIA)

The read endpoints marked below honor an optional x-client-type request header (web or mobile). When the header is absent it defaults to mobile; any other value returns 400.

x-client-type: mobile (default) → a lean payload (raw entity; sensitive/audit fields and heavy relations stripped). Audit columns stay flat: created_at/updated_at + *_by UUIDs, and relations are exposed as FK ids (e.g. customization_id).
x-client-type: web → a formatted, enriched payload (extra relations, attached documents where relevant, and a normalized shape). Audit fields are nested into created/updated/deleted { at, by } objects, and relations like account and customization are returned as objects.

Web clients must send x-client-type: web to receive the enriched shape. For the full cross-module explanation see Client types (web vs mobile).

`POST /v1/saving-goals` bearer

Create a new saving goal. Ownership is always derived from the JWT (Architecture B): INDIVIDUAL → individual-owned goal for the caller; ORGANIZATION → organization-owned goal for the caller’s org; MORIA → may set owner_type=MORIA. Org admins may pass an optional user_id to create an individual-owned goal on behalf of a member of their own organization. The holding account is created automatically server-side.

bearer create-saving-goal SAVING_GOAL_CREATED

Request body — `CreateSavingGoalDto`

Field	Type	Required	Notes
`user_id`	string (UUID)	optional	New. Only meaningful when the caller is an organization admin — create an INDIVIDUAL-owned goal on behalf of a member of the admin’s own organization. Ignored for individual callers (must match own `user.id` if sent — otherwise 403). When omitted, an org caller creates an ORGANIZATION-owned goal and an individual caller creates a goal for themselves.
`name`	string	✓	Goal name (e.g. `Hajj`)
`liquidity_type`	enum `LiquidityType`	optional	`loose` (default) or `locked`
`target_amount`	string	✓	Target nominal as a numeric string (rupiah, integer)
`start_date`	date (ISO 8601)	✓	Accumulation start date (`YYYY-MM-DD`)
`end_date`	date (ISO 8601)	✓	Target completion date (`YYYY-MM-DD`)
`deduction_amount`	string	✓	Periodic auto-deduction nominal (rupiah)
`deduction_date`	string	✓	Day of month (`1`..`28`) when auto-deduction runs
`owner_type`	enum `OwnerType`	optional	Set to `MORIA` (requires `user_type=MORIA`) to create a Moria-owned goal. Ignored for INDIVIDUAL/ORGANIZATION callers — `owner_type` is inferred from the JWT.

Example request

{
  "name": "Hajj",
  "liquidity_type": "loose",
  "target_amount": "2400",
  "start_date": "2026-02-06",
  "end_date": "2027-02-06",
  "deduction_amount": "200",
  "deduction_date": "25"
}

Response — `201 Created`

{
  "status": "success",
  "statusCode": 201,
  "message": "Saving goal created successfully",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Hajj",
    "slug_name": "hajj",
    "target_amount": "2400.0000",
    "saved_amount": "0.0000",
    "deduction_amount": "200.0000",
    "deduction_date": "2026-02-25",
    "start_date": "2026-02-06",
    "end_date": "2027-02-06",
    "duration": 12,
    "status": "active",
    "liquidity_type": "loose",
    "owner_type": "individual",
    "owner_id": "770e8400-e29b-41d4-a716-446655440222",
    "account_id": "880e8400-e29b-41d4-a716-446655440333",
    "created_at": "2026-05-20T08:30:00.000Z"
  }
}

Errors

Status	When it occurs
`400 Bad Request`	Validation failed (invalid date, non-numeric amount, unknown field — including legacy `account_id`/`organization_id`)
`401 Unauthorized`	Bearer/cookie token invalid
`403 Forbidden`	Missing `create-saving-goal` permission · individual caller sent a `user_id` that does not match their own · org admin sent a `user_id` for a user outside their organization

Side effects

Creates a new row in saving_goals + a holding accounts row (atomic, transactional).
Emits BusinessEvent SAVING_GOAL_CREATED (impact MEDIUM).
Starts the auto-deduction scheduler based on deduction_date.

`GET /v1/saving-goals` bearer

List the saving goals belonging to the logged-in user or organization. Supports layered filters and pagination.

Scope depends on role:

INDIVIDUAL — own goals only (owner_id = caller), plus organization-owned goals in the caller’s own org they’re entitled to view.
ORGANIZATION admin — default (type=all) returns the combined set: org-owned goals (owner_type=ORGANIZATION, owner_id=admin's org) and goals owned by individual members of the same organization. type=organization returns only org-owned; type=individual returns only the org’s member-individual goals (scoped via users.organization_id — does not leak across organizations). When user_id is supplied (must belong to the admin’s org), it narrows to that one member’s goals.
MORIA — unrestricted across all owner types.

Web / mobile — honors x-client-type (default mobile). web → formatted list (formatSavingGoalList()); mobile → raw, with account and audit fields (created_by/updated_by/deleted_by) stripped.

bearer read-saving-goal RESOURCE_FETCHED

Query params

Param	Type	Default	Notes
`page`	number	`1`	Page number
`limit`	number	`10`	Records per page
`status`	enum `SavingGoalStatus`	optional	`new`, `active`, `paused`, `cancelled`, `completed`, `converted`
`liquidity_type`	enum `LiquidityType`	optional	`loose` or `locked`
`order`	`'asc' \| 'desc'`	`desc`	Sort by `created_at`
`type`	enum `SavingGoalFetchType`	optional	`individual`, `organization`, `all`, `due_saving_goals`, `moria`. For INDIVIDUAL always forced to `individual`. For ORG admin: `all` (default) → combined org-owned + member-individual; `organization` → org-owned only; `individual` → member-individual only (org-scoped).
`user_id`	string (UUID)	optional	Filter by user; INDIVIDUAL may only use their own user.id
`account_id`	string (UUID)	optional	Filter by account; INDIVIDUAL may only use their own account

Response — `mobile` (default)

{
  "status": "success",
  "statusCode": 200,
  "message": "all saving goals fetched successfully",
  "data": {
    "limit": 10,
    "count": 146,
    "currentPage": 1,
    "totalPages": 15,
    "savingGoals": [
      {
        "id": "c55b0bfb-d13d-4c38-811f-e60fb5807f93",
        "created_at": "2026-05-26T07:40:49.755Z",
        "updated_at": "2026-05-26T07:40:49.000Z",
        "name": "Demo Hajj Cancelled",
        "slug_name": "demo_hajj_cancelled",
        "owner_type": "individual",
        "owner_id": "5ebbf5f6-9e18-421c-8f1d-d6286adcd2b0",
        "customization_id": "5b482830-f39f-460e-8931-0a63b96fd541",
        "account_id": "c34d8dfd-79c7-4776-aec9-00ba476c0802",
        "status": "cancelled",
        "liquidity_type": "loose",
        "saved_amount": "0.0000",
        "target_amount": "2400000.0000",
        "deduction_amount": "200000.0000",
        "deduction_date": "2026-06-25",
        "start_date": "2026-05-26",
        "end_date": "2027-05-26",
        "deduction_failed_attempts": 0,
        "deduction_next_retry_date": null,
        "duration": 12,
        "customization": {
          "id": "5b482830-f39f-460e-8931-0a63b96fd541",
          "created_at": "2026-05-26T07:40:49.764Z",
          "updated_at": "2026-05-26T07:40:49.764Z",
          "created_by": "5ebbf5f6-9e18-421c-8f1d-d6286adcd2b0",
          "updated_by": "00000000-0000-0000-0000-000000000000",
          "deleted_by": "00000000-0000-0000-0000-000000000000",
          "reference_id": "c55b0bfb-d13d-4c38-811f-e60fb5807f93",
          "icon": "https://example.com/icon.png",
          "theme": "light",
          "color": "blue",
          "reference_type": "saving_goal"
        }
      }
    ]
  },
  "lang": "en"
}

Response — `web` (`x-client-type: web`)

{
  "status": "success",
  "statusCode": 200,
  "message": "all saving goals fetched successfully",
  "data": {
    "limit": 10,
    "count": 146,
    "currentPage": 1,
    "totalPages": 15,
    "savingGoals": [
      {
        "id": "c55b0bfb-d13d-4c38-811f-e60fb5807f93",
        "created": {
          "at": "2026-05-26T07:40:49.755Z",
          "by": {}
        },
        "updated": {
          "at": "2026-05-26T07:40:49.000Z",
          "by": {}
        },
        "deleted": {
          "at": null,
          "by": {}
        },
        "name": "Demo Hajj Cancelled",
        "status": "cancelled",
        "liquidity_type": "loose",
        "owner_type": "individual",
        "owner_id": "5ebbf5f6-9e18-421c-8f1d-d6286adcd2b0",
        "saved_amount": "0.0000",
        "target_amount": "2400000.0000",
        "deduction_amount": "200000.0000",
        "deduction_date": "2026-06-25",
        "start_date": "2026-05-26",
        "end_date": "2027-05-26",
        "duration": 12,
        "account": {
          "id": "c34d8dfd-79c7-4776-aec9-00ba476c0802",
          "account_number": "SG-XDCPS4HAQY",
          "name": "Demo Hajj Cancelled",
          "account_type": "saving_goal"
        },
        "customization": {
          "id": "5b482830-f39f-460e-8931-0a63b96fd541",
          "color": "blue",
          "theme": "light",
          "icon": "https://example.com/icon.png"
        }
      }
    ]
  },
  "lang": "en"
}

Errors

Status	When it occurs
`400 Bad Request`	Invalid query param
`401 Unauthorized`	Bearer/cookie token invalid
`403 Forbidden`	INDIVIDUAL sends another user’s `user_id`/`account_id` · ORGANIZATION admin sends a user from another org

`GET /v1/saving-goals/:id` bearer

Detail of a single saving goal. Authorization is checked in layers: INDIVIDUAL must be the owner, ORGANIZATION admin must be from the same org, MORIA is unrestricted. The response format differs between WEB (richer) and MOBILE (raw entity).

Web / mobile — honors x-client-type (default mobile). web → formatted detail incl. account, customization, and contributions; mobile → raw entity with account stripped.

bearer read-saving-goal RESOURCE_FETCHED

Path params

Param	Type	Notes
`id`	UUID	Saving goal ID — validated via `ParseUUIDPipe`

Response — `mobile` (default)

{
  "status": "success",
  "statusCode": 200,
  "message": "Saving goal fetched successfully",
  "data": {
    "savingGoal": {
      "id": "c55b0bfb-d13d-4c38-811f-e60fb5807f93",
      "created_at": "2026-05-26T07:40:49.755Z",
      "updated_at": "2026-05-26T07:40:49.000Z",
      "created_by": "5ebbf5f6-9e18-421c-8f1d-d6286adcd2b0",
      "updated_by": "5ebbf5f6-9e18-421c-8f1d-d6286adcd2b0",
      "deleted_by": "00000000-0000-0000-0000-000000000000",
      "name": "Demo Hajj Cancelled",
      "slug_name": "demo_hajj_cancelled",
      "owner_type": "individual",
      "owner_id": "5ebbf5f6-9e18-421c-8f1d-d6286adcd2b0",
      "customization_id": "5b482830-f39f-460e-8931-0a63b96fd541",
      "account_id": "c34d8dfd-79c7-4776-aec9-00ba476c0802",
      "status": "cancelled",
      "liquidity_type": "loose",
      "saved_amount": "0.0000",
      "target_amount": "2400000.0000",
      "deduction_amount": "200000.0000",
      "deduction_date": "2026-06-25",
      "start_date": "2026-05-26",
      "end_date": "2027-05-26",
      "deduction_failed_attempts": 0,
      "deduction_next_retry_date": null,
      "duration": 12,
      "customization": {
        "id": "5b482830-f39f-460e-8931-0a63b96fd541",
        "created_at": "2026-05-26T07:40:49.764Z",
        "updated_at": "2026-05-26T07:40:49.764Z",
        "created_by": "5ebbf5f6-9e18-421c-8f1d-d6286adcd2b0",
        "updated_by": "00000000-0000-0000-0000-000000000000",
        "deleted_by": "00000000-0000-0000-0000-000000000000",
        "reference_id": "c55b0bfb-d13d-4c38-811f-e60fb5807f93",
        "icon": "https://example.com/icon.png",
        "theme": "light",
        "color": "blue",
        "reference_type": "saving_goal"
      }
    }
  },
  "lang": "en"
}

Response — `web` (`x-client-type: web`)

{
  "status": "success",
  "statusCode": 200,
  "message": "Saving goal fetched successfully",
  "data": {
    "savingGoal": {
      "id": "c55b0bfb-d13d-4c38-811f-e60fb5807f93",
      "created": {
        "at": "2026-05-26T07:40:49.755Z",
        "by": {}
      },
      "updated": {
        "at": "2026-05-26T07:40:49.000Z",
        "by": {}
      },
      "deleted": {
        "at": null,
        "by": {}
      },
      "name": "Demo Hajj Cancelled",
      "status": "cancelled",
      "liquidity_type": "loose",
      "owner_type": "individual",
      "owner_id": "5ebbf5f6-9e18-421c-8f1d-d6286adcd2b0",
      "saved_amount": "0.0000",
      "target_amount": "2400000.0000",
      "deduction_amount": "200000.0000",
      "deduction_date": "2026-06-25",
      "start_date": "2026-05-26",
      "end_date": "2027-05-26",
      "duration": 12,
      "account": {
        "id": "c34d8dfd-79c7-4776-aec9-00ba476c0802",
        "account_number": "SG-XDCPS4HAQY",
        "name": "Demo Hajj Cancelled",
        "account_type": "saving_goal"
      },
      "customization": {
        "id": "5b482830-f39f-460e-8931-0a63b96fd541",
        "color": "blue",
        "theme": "light",
        "icon": "https://example.com/icon.png"
      },
      "member_contributions": [
        {
          "user_id": "",
          "total_contribution": "0.00",
          "contribution_count": 0
        }
      ]
    }
  },
  "lang": "en"
}

Errors

Status	When it occurs
`400 Bad Request`	`id` is not a UUID
`401 Unauthorized`	Bearer/cookie token invalid
`403 Forbidden`	Not the owner / not from the same org / not MORIA for a MORIA goal
`404 Not Found`	Goal not found

`PATCH /v1/saving-goals/:id` bearer

Update saving goal parameters (name, target, deduction, status). All fields are optional — send only what changed. A completed status from the client is reset to active by the server.

bearer update-saving-goal SAVING_GOAL_UPDATED

Path params

Param	Type	Notes
`id`	UUID	Saving goal ID

Request body — `UpdateSavingGoalDto`

Field	Type	Notes
`name`	string	New name
`target_amount`	string	New target nominal
`start_date`	date (ISO 8601)	New start date
`end_date`	date (ISO 8601)	New end date
`deduction_amount`	string	New auto-deduction nominal
`deduction_date`	numeric string	Day of month for auto-deduction
`status`	enum `SavingGoalStatus`	`new`, `active`, `paused`, `cancelled`, `completed`, `converted` (server forces `completed` → `active`)

Example request

{
  "name": "Hajj 2027",
  "target_amount": "3000",
  "deduction_amount": "250"
}

Response — `200 OK`

{
  "status": "success",
  "statusCode": 200,
  "message": "Saving goal updated successfully",
  "data": { "...": "same shape as SavingGoalDto" }
}

Errors

Status	When it occurs
`400 Bad Request`	Validation failed
`401 Unauthorized`	Bearer/cookie token invalid
`403 Forbidden`	Not the goal owner
`404 Not Found`	Goal not found

`PATCH /v1/saving-goals/:id/pause` bearer

Toggle pause/unpause for auto-deduction. While paused, the periodic scheduler does not deduct funds until it is resumed.

bearer pause-saving-goal SAVING_GOAL_UPDATED

Path params

Param	Type	Notes
`id`	UUID	Saving goal ID

Request body — `PauseSavingGoalsDto`

Field	Type	Required	Notes
`pause`	boolean	✓	`true` → pause, `false` → resume

Example request

{ "pause": true }

Response — `200 OK`

{
  "status": "success",
  "statusCode": 200,
  "message": "Saving goal paused successfully",
  "data": { "...": "SavingGoalDto shape, status changes to 'paused' or 'active'" }
}

Errors

Status	When it occurs
`400 Bad Request`	`pause` is not a boolean
`401 Unauthorized`	Bearer/cookie token invalid
`403 Forbidden`	Not the goal owner
`404 Not Found`	Goal not found

`PATCH /v1/saving-goals/:id/manual-deduction` bearer

Run a manual deduction when auto-deduction fails or the user wants to top up outside the schedule. A goal already completed rejects the request and returns 200 with an informative message.

bearer update-saving-goal RESOURCE_UPDATED

Path params

Param	Type	Notes
`id`	UUID	Saving goal ID

Request body — `ManualDeductionDto`

Field	Type	Required	Notes
`deduction_amount`	numeric string	✓	Amount deducted from the source account to the holding account; `IsNotZero` + `IsValidDecimal`

Example request

{ "deduction_amount": "500" }

Response — `200 OK`

{
  "status": "success",
  "statusCode": 200,
  "message": "Manual deduction processed successfully",
  "data": { "...": "SavingGoalDto shape, saved_amount increased" }
}

If the goal is already completed, response: { "statusCode": 200, "message": "Saving goal is already completed!" } — no deduction is performed.

Errors

Status	When it occurs
`400 Bad Request`	`deduction_amount` is zero / non-decimal
`401 Unauthorized`	Bearer/cookie token invalid
`403 Forbidden`	Not the goal owner / insufficient account balance
`404 Not Found`	Goal not found

`DELETE /v1/saving-goals/:id` bearer

Delete a saving goal. Permanent operation (soft-delete via deleted_at from AuditableEntity); the holding account balance is handled by the service.

bearer delete-saving-goal SAVING_GOAL_DELETED

Path params

Param	Type	Notes
`id`	UUID	Saving goal ID

Response — `200 OK`

{
  "status": "success",
  "statusCode": 200,
  "message": "Saving goal deleted successfully"
}

Errors

Status	When it occurs
`401 Unauthorized`	Bearer/cookie token invalid
`403 Forbidden`	Not the goal owner
`404 Not Found`	Goal not found

Side effects

Emits BusinessEvent SAVING_GOAL_DELETED (impact HIGH).
Sub-records still holding a balance in the holding account are moved/retained per service logic.

`GET /v1/summary/saving-goals` bearer

Aggregate saving goals summary for the organization of the logged-in user. Admin endpoint — only MORIA and ORGANIZATION are allowed. Useful for analytics dashboards (counts, totals, averages, progress).

bearer MORIA, ORGANIZATION read-saving-goal RESOURCE_FETCHED

Response — `200 OK`

{
  "status": "success",
  "statusCode": 200,
  "message": "saving goals summary fetched successfully",
  "data": {
    "organization_id": "660e8400-e29b-41d4-a716-446655440111",
    "organization_name": "Moria Fund",
    "total_goals": "10",
    "total_saved_amount": "25000000.00",
    "total_target_amount": "100000000.00",
    "total_deduction_amount": "5000000.00",
    "new_goals": "2",
    "active_goals": "5",
    "paused_goals": "1",
    "cancelled_goals": "0",
    "completed_goals": "2",
    "avg_duration_months": "12",
    "avg_progress_percentage": "35.00",
    "goals_reached_target": "2"
  }
}

Errors

Status	When it occurs
`401 Unauthorized`	Bearer/cookie token invalid
`403 Forbidden`	Role is not `MORIA`/`ORGANIZATION` or missing permission

Reference

Enum: `SavingGoalStatus`

new — newly created, not yet running
active — auto-deduction running
paused — auto-deduction paused
cancelled — cancelled by user/admin
completed — target reached
converted — converted into an investment (see Investments module)

Enum: `LiquidityType`

loose — funds can be withdrawn at any time (default)
locked — funds locked until end_date

Enum: `SavingGoalFetchType`

individual, organization, all, moria, due_saving_goals

Enum: `OwnerType`

individual · organization · moria

Standard error envelope

{
  "message": "deduction_amount must be a number string",
  "statusCode": 400,
  "error": "Bad Request"
}

message can be a string or an array of strings (multi-field validation errors).

Common HTTP codes

400 body/query/param validation
401 token expired / missing
403 not the owner / wrong scope / insufficient balance
404 goal not found
500 internal — show a generic toast

Saving Goals

Summary

POST /v1/saving-goals bearer

Request body — CreateSavingGoalDto

Example request

Response — 201 Created

Errors

Side effects

GET /v1/saving-goals bearer

Query params

Response — mobile (default)

Response — web (x-client-type: web)

Errors

GET /v1/saving-goals/:id bearer

Path params

Response — mobile (default)

Response — web (x-client-type: web)

Errors

PATCH /v1/saving-goals/:id bearer

Path params

Request body — UpdateSavingGoalDto

Example request

Response — 200 OK

Errors

PATCH /v1/saving-goals/:id/pause bearer

Path params

Request body — PauseSavingGoalsDto

Example request

Response — 200 OK

Errors

PATCH /v1/saving-goals/:id/manual-deduction bearer

Path params

Request body — ManualDeductionDto

Example request

Response — 200 OK

Errors

DELETE /v1/saving-goals/:id bearer

Path params

Response — 200 OK

Errors

Side effects

GET /v1/summary/saving-goals bearer

Response — 200 OK

Errors

Reference

Enum: SavingGoalStatus

Enum: LiquidityType

Enum: SavingGoalFetchType

Enum: OwnerType

Standard error envelope

Common HTTP codes

`POST /v1/saving-goals` bearer

Request body — `CreateSavingGoalDto`

Response — `201 Created`

`GET /v1/saving-goals` bearer

Response — `mobile` (default)

Response — `web` (`x-client-type: web`)

`GET /v1/saving-goals/:id` bearer

Response — `mobile` (default)

Response — `web` (`x-client-type: web`)

`PATCH /v1/saving-goals/:id` bearer

Request body — `UpdateSavingGoalDto`

Response — `200 OK`

`PATCH /v1/saving-goals/:id/pause` bearer

Request body — `PauseSavingGoalsDto`

Response — `200 OK`

`PATCH /v1/saving-goals/:id/manual-deduction` bearer

Request body — `ManualDeductionDto`

Response — `200 OK`

`DELETE /v1/saving-goals/:id` bearer

Response — `200 OK`

`GET /v1/summary/saving-goals` bearer

Response — `200 OK`

Enum: `SavingGoalStatus`

Enum: `LiquidityType`

Enum: `SavingGoalFetchType`

Enum: `OwnerType`