Care Package Module - API & Integration Guide

1. Quick Metadata

• Module: Care Package
• Auth models:
  • Customer/mobile routes: JwtAuthGuard (via @CurrentUser("id"))
  • Admin routes: JwtAuthGuard + RoleGuard + @Permissions(...)
• Primary base URLs:
  • Customer eligibility: /api/care-packages | mobile: /api/mobile/care-packages
  • Customer cart: /api/cart/items/:cartItemId/care-package | mobile: /api/mobile/cart/items/:cartItemId/care-package
  • Customer subscriptions: /api/me/care-packages | mobile: /api/mobile/me/care-packages
  • Customer redemptions: /api/me/care-packages/:subscriptionId/requests | mobile: same with /api/mobile/ prefix
  • Admin packages: /api/admin/care-packages
  • Admin subscriptions: /api/admin/care-package-subscriptions
  • Admin redemptions: /api/admin/care-package-redemptions
• Response envelope: ResponseDto<T> for all successful responses
• Swagger tags: Care Packages (Admin), Care Packages (Mobile), Cart (Mobile), Care Package Subscriptions (Admin), Care Package Subscriptions (Mobile), Care Package Redemptions (Admin), Care Package Redemptions (Mobile)

2. Route Summary Tables

Admin — Care Packages

Admin — Subscriptions

Admin — Redemptions

Customer/Mobile

| Method | Path | Auth | |---|---|---|---| | GET | /api/mobile/care-packages/available | Public | | GET | /api/mobile/care-packages/:slug | Public | | GET | /api/mobile/care-packages/:slug/cart-eligibility | Public (JWT optional) | | POST | /api/mobile/cart/guest/quote | Public | | POST | /api/mobile/cart/sync | JWT | | POST | /api/mobile/cart/items/:cartItemId/care-package | JWT | | DELETE | /api/mobile/cart/items/:cartItemId/care-package | JWT | | GET | /api/mobile/me/care-packages | JWT | | GET | /api/mobile/me/care-packages/:id | JWT | | POST | /api/mobile/me/care-packages/:subscriptionId/requests | JWT | | GET | /api/mobile/me/care-packages/:subscriptionId/requests | JWT | | GET | /api/mobile/me/care-packages/:subscriptionId/requests/:requestId | JWT | | POST | /api/mobile/me/care-packages/:subscriptionId/requests/:requestId/cancel | JWT |

3. Key Request/Response Shapes

Admin Create Care Package

POST /api/admin/care-packages
{
  "name": "Basic Care",
  "description": "Entry-level care package.",
  "sortOrder": 0,
  "termsAndConditions": "## T&C\n...",
  "seoId": "01966e65-0001-7000-aaaa-000000000001"
}

seoId is optional. Omit or pass null to create a package without SEO metadata.

Admin Update Care Package

PUT /api/admin/care-packages/:id
{
  "name": "Updated Care",
  "seoId": "01966e65-0001-7000-aaaa-000000000001"
}

Name change auto-regenerates the slug and records the previous slug in care_package_slug_history.

Get Available Care Packages (Customer)

GET /api/mobile/care-packages/available

Response 200:
{
  "success": true,
  "message": "Available care packages fetched",
  "data": [
    {
      "id": 1,
      "name": "Basic Care",
      "slug": "basic-care",
      "description": "Entry-level care coverage.",
      "sortOrder": 0,
      "termsAndConditions": null,
      "features": [
        { "featureType": "repair", "isEnabled": true, "isUnlimited": false, "usageCount": 2, "notes": null }
      ],
      "pricingTiers": [
        { "id": 1, "durationMonths": 12, "basePrice": 99900, "discountAmount": 0, "effectivePrice": 99900 }
      ]
    }
  ]
}

Optional query params: productId, categoryId, subcategoryId, brandId, brandSeriesId, minPrice, maxPrice. Response is cached. Use slug to fetch full details via GET /care-packages/:slug.

Get Care Package by Slug (Customer)

GET /api/mobile/care-packages/basic-care

Response 200:
{
  "success": true,
  "message": "Care package fetched successfully",
  "data": {
    "id": 1,
    "name": "Basic Care",
    "slug": "basic-care",
    "description": "Entry-level care package.",
    "termsAndConditions": null,
    "seo": {
      "metaTitle": "Basic Care Package",
      "metaDescription": "Get covered with Basic Care.",
      "ogTitle": "Basic Care Package",
      "ogType": "website",
      "structuredDataJsonLd": null
    },
    "features": [
      { "id": 1, "featureType": "repair", "isEnabled": true, "isUnlimited": false, "usageCount": 2, "notes": null, "featureMetadata": null }
    ],
    "pricingTiers": [
      { "id": 1, "durationMonths": 12, "basePrice": 99900, "discountAmount": 0, "sortOrder": 0 }
    ],
    "eligibilityCoverage": {
      "categories": [{ "id": 5, "name": "Electronics" }],
      "brands": [{ "id": 3, "name": "Apple" }, { "id": 7, "name": "Samsung" }],
      "brandSeries": [{ "id": 12, "name": "iPhone 15 Series" }],
      "products": [{ "id": 42, "title": "iPhone 15 Pro Max 256GB", "thumbnailUrl": "https://cdn.example.com/thumb.jpg" }],
      "priceRange": { "minPrice": 5000000, "maxPrice": null }
    },
    "createdAt": "2026-01-01T00:00:00.000Z",
    "updatedAt": "2026-01-01T00:00:00.000Z"
  }
}

The eligibilityCoverage field shows the included criteria — categories, brands, brand series, and specific products that this care package covers. priceRange shows the applicable price window when present. null means the package has no configured rules (covers everything) or only exclusion rules. This field is resolved at read time from the care_package_eligibility_rule table and enriched with display names from the catalog tables.

Historical slugs (old slugs from before a name change) also resolve to the current active package. Returns 404 for inactive, draft, or non-existent slugs.

Get Cart Eligibility (User)

GET /api/mobile/care-packages/basic-care/cart-eligibility

Response 200 (with eligible items):
{
  "success": true,
  "message": "Cart eligibility fetched successfully",
  "data": {
    "eligibleItems": [
      { "cartItemId": 5, "productId": 42, "title": "iPhone 15 Pro Max 256GB", "thumbnailUrl": "https://cdn.example.com/thumb.jpg", "quantity": 1 }
    ],
    "ineligibleItems": [
      { "cartItemId": 3, "productId": 15, "title": "Screen Protector", "thumbnailUrl": null, "quantity": 2 }
    ]
  }
}

The eligibleItems array contains cart items whose product category, brand, series, or price match the care package's inclusion rules. ineligibleItems are cart items that do not match. When the user has no active cart or no items, both arrays are empty. Guest users (no JWT) also receive empty arrays.

Add Care Package to Cart Item

POST /api/mobile/cart/items/:cartItemId/care-package
{
  "carePackageId": 1,
  "pricingTierId": 3
}

This endpoint is JWT-only. Guest clients can price a selected care package through POST /api/mobile/cart/guest/quote, then persist the same selection through POST /api/mobile/cart/sync after login. Direct add validates ownership, physical product kind, active package state, product eligibility rules, and active pricing tier before writing cartCarePackageItems.

Raise Redemption Request

POST /api/mobile/me/care-packages/:subscriptionId/requests
{
  "featureType": "repair",
  "description": "Screen cracked, need repair.",
  "attachmentUrls": ["https://..."],
  "requestMetadata": {}
}

Admin Suspend Subscription

POST /api/admin/care-package-subscriptions/:id/suspend
{
  "reason": "Customer requested suspension pending investigation."
}

Admin Update Redemption Status

PUT /api/admin/care-package-redemptions/:id/status
{
  "status": "accepted",
  "adminNotes": "Approved for in-person repair."
}

My Subscription Detail Response (Key Fields)

{
  "id": 42,
  "carePackageId": 5,
  "slug": "premium-care",
  "status": "active",
  "startDate": "2026-01-15",
  "expiryDate": "2027-01-15",
  "remainingDays": 212,
  "packageName": "Premium Care",
  "termsAndConditions": "...",
  "featureSlots": [
    {
      "featureType": "repair",
      "isUnlimited": false,
      "usageLimit": 3,
      "usedCount": 1,
      "remainingSlots": 2,
      "notes": null
    }
  ]
}

4. Pagination and Filtering

List endpoints support standard pagination query params: pagination (boolean), page, size.

Filterable fields:

• GET /api/admin/care-package-subscriptions: status, customerId, carePackageId
• GET /api/admin/care-package-redemptions: status, subscriptionId, featureType, customerId
• GET /api/mobile/me/care-packages: status
• GET /api/mobile/me/care-packages/:subscriptionId/requests: status