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)

Auth + scope notes

• Every endpoint requires Bearer JWT. @Permissions(...) is checked in addition to the role guard.
• INDIVIDUAL may only access their own goals; user_id/account_id filters are forced to their own data.
• ORGANIZATION admins may query any user in their organization; sending a user_id from another org → 403.
• MORIA superadmin is unrestricted; can create goals with owner_type=moria.
• The account_id field on the create-saving-goal DTO is effectively optional under Architecture B (holding account auto-created); send it only when you already have a dedicated account.

---

POST /v1/saving-goals bearer

Create a new saving goal for the currently logged-in user. The service automatically creates a dedicated holding account per goal (Architecture B). For admins (MORIA/ORGANIZATION) the goal is created on behalf of the organization; for INDIVIDUAL the goal is owned by the user themselves.

bearer create-saving-goal SAVING_GOAL_CREATED

Request body — CreateSavingGoalDto

Field	Type	Required	Notes
account_id	string (UUID)	optional	Source account (if one already exists); empty → service creates a new holding account
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	Only applies to MORIA superadmin; ignored for INDIVIDUAL/ORGANIZATION (inferred from user_type)

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)
401 Unauthorized	Bearer/cookie token invalid
403 Forbidden	Missing create-saving-goal permission

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. Authorization: INDIVIDUAL is limited to own data, ORGANIZATION admin to their organization, MORIA is unrestricted.

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
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 — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "Saving goals retrieved successfully",
  "data": {
    "limit": 10,
    "count": 24,
    "currentPage": 1,
    "totalPages": 3,
    "saving_goals": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Hajj",
        "slug_name": "hajj",
        "target_amount": "2400.0000",
        "saved_amount": "850.0000",
        "deduction_amount": "200.0000",
        "deduction_date": "2026-02-25",
        "status": "active",
        "liquidity_type": "loose",
        "owner_type": "individual",
        "owner_id": "770e8400-e29b-41d4-a716-446655440222",
        "account_id": "880e8400-e29b-41d4-a716-446655440333",
        "duration": 12,
        "created_at": "2026-05-20T08:30:00.000Z"
      }
    ]
  }
}

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).

bearer read-saving-goal RESOURCE_FETCHED

Path params

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

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "saving goal fetched successfully",
  "data": {
    "savingGoal": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Hajj",
      "slug_name": "hajj",
      "target_amount": "2400.0000",
      "saved_amount": "850.0000",
      "deduction_amount": "200.0000",
      "deduction_date": "2026-02-25",
      "start_date": "2026-02-06",
      "end_date": "2027-02-06",
      "duration": 12,
      "deduction_failed_attempts": 0,
      "deduction_next_retry_date": null,
      "status": "active",
      "liquidity_type": "loose",
      "owner_type": "individual",
      "owner_id": "770e8400-e29b-41d4-a716-446655440222",
      "account_id": "880e8400-e29b-41d4-a716-446655440333"
    }
  }
}

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