Customization

The customization module stores the visual appearance (icon, color, theme) for savings products: saving_goal, saving_circle, commodity_financing, charitable_cause. Customization records are created automatically by each product’s service (the POST endpoint is disabled); FE only accesses them through list, detail, update, and delete on the /customizations route.

Property	Value
Base URL	{HOST}/v1
Auth	Bearer JWT (header Authorization) or access_token cookie
Content-Type	application/json
Error envelope	{ "message": string | string[], "statusCode": number, "error": string }
Validation	Global ValidationPipe · whitelist: true, forbidNonWhitelisted: true
Related modules	saving-goals, saving-circles, commodity-financing, charitable-cause
Document version	v1 · 2026-05-20
Audience	Internal FE devs (mobile + web)

Summary

Four active endpoints: list all customizations, get detail by UUID, update theme/icon/color, and delete. The POST /customizations endpoint exists in source but is commented-out — customization records are created as a side effect by the product modules (e.g. when creating a saving goal).

Method	Path	Auth	Summary
GET	/v1/customizations	bearer	List all customizations
GET	/v1/customizations/:id	bearer	Customization detail by UUID
PATCH	/v1/customizations/:id	bearer	Update icon/color/theme
DELETE	/v1/customizations/:id	bearer	Soft delete a customization

Notes

• No @Permissions or @Roles on the controller — the global Bearer guard is sufficient.
• All :id are validated via ParseUUIDPipe — send UUID v4 or get a 400.
• theme is an enum: dark, light, system. reference_type in the response: saving_goal, saving_circle, commodity_financing, charitable_cause.
• The color field in the DB is a string of length 9 (likely a hex code with alpha, e.g. #FF5733FF).

---

GET /v1/customizations bearer

Retrieve all customizations. The service returns { customizations, total }.

bearer

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "Customizations retrieved successfully",
  "data": {
    "customizations": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "reference_id": "660e8400-e29b-41d4-a716-446655440111",
        "icon": "star",
        "theme": "light",
        "color": "#FF5733",
        "reference_type": "saving_goal",
        "created_by": "770e8400-e29b-41d4-a716-446655440222",
        "updated_by": "770e8400-e29b-41d4-a716-446655440222",
        "deleted_by": null,
        "created_at": "2026-05-20T08:30:00.000Z",
        "updated_at": "2026-05-20T08:30:00.000Z"
      }
    ],
    "total": 1
  }
}

Errors

Status	When it occurs
401 Unauthorized	Bearer/cookie is invalid

---

GET /v1/customizations/:id bearer

Detail of one customization. ID must be UUID v4.

bearer

Path params

Param	Type	Notes
id	UUID	Validated via ParseUUIDPipe

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "Customization retrieved successfully",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "reference_id": "660e8400-e29b-41d4-a716-446655440111",
    "icon": "star",
    "theme": "light",
    "color": "#FF5733",
    "reference_type": "saving_goal",
    "created_by": "770e8400-e29b-41d4-a716-446655440222",
    "updated_by": "770e8400-e29b-41d4-a716-446655440222",
    "deleted_by": null,
    "created_at": "2026-05-20T08:30:00.000Z",
    "updated_at": "2026-05-20T08:30:00.000Z"
  }
}

Errors

Status	When it occurs
400 Bad Request	id is not a UUID
401 Unauthorized	Bearer/cookie is invalid
404 Not Found	Customization not found

---

PATCH /v1/customizations/:id bearer

Update a customization. The theme field is required (see DTO). Other fields are optional via PartialType(CreateCustomizationDto).

bearer

Path params

Param	Type	Notes
id	UUID	Validated via ParseUUIDPipe

Request body — UpdateCustomizationDto

Field	Type	Required	Notes
theme	enum Theme	✓	dark, light, system (entity default: light)
refrence_id	string	optional	Note: the DTO spelling is indeed refrence_id (without the second “e”). Mobile FE already consumes this name — leave it as-is.
icon	string	optional	Icon name or URL
color	string	optional	Hex code, max length 9 chars

Example request

{
  "theme": "dark",
  "color": "#1E1B4B"
}

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "Customization updated successfully",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "reference_id": "660e8400-e29b-41d4-a716-446655440111",
    "icon": "star",
    "theme": "dark",
    "color": "#1E1B4B",
    "reference_type": "saving_goal",
    "created_by": "770e8400-e29b-41d4-a716-446655440222",
    "updated_by": "770e8400-e29b-41d4-a716-446655440222",
    "deleted_by": null,
    "created_at": "2026-05-20T08:30:00.000Z",
    "updated_at": "2026-05-20T09:00:00.000Z"
  }
}

Errors

Status	When it occurs
400 Bad Request	id is not a UUID, theme invalid, or non-whitelisted field
401 Unauthorized	Bearer/cookie is invalid
404 Not Found	Customization not found

---

DELETE /v1/customizations/:id bearer

Soft delete a customization. The service calls softDeleteCustomization — the record remains but deleted_at/deleted_by are set.

bearer

Path params

Param	Type	Notes
id	UUID	Validated via ParseUUIDPipe

Response — 200 OK

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

Errors

Status	When it occurs
400 Bad Request	id is not a UUID
401 Unauthorized	Bearer/cookie is invalid
404 Not Found	Customization not found

---

Reference

Enum: Theme

• dark
• light — entity default
• system

Enum: CustomizationReferenceType

• saving_goal
• saving_circle
• commodity_financing
• charitable_cause

Standard error envelope

{
  "message": "Validation failed (uuid is expected)",
  "statusCode": 400,
  "error": "Bad Request"
}

Common HTTP codes

• 400 body/param validation
• 401 missing / expired token
• 404 customization not found

The POST /customizations endpoint exists in source code but is commented-out. Records are created automatically by the product modules (saving-goals, saving-circles, etc.).