Patient Package Subscriptions API

OverviewCopy Anchor Link

The Patient Package Subscriptions API provides endpoints for managing patient subscriptions to care packages. This allows patients to subscribe to service packages that include multiple healthcare services at discounted rates.

Base URL: /api

Authentication: Bearer token required

Headers:

Authorization: Bearer {token}
X-Tenant-ID: {tenant_id}

EndpointsCopy Anchor Link

1. List All SubscriptionsCopy Anchor Link

List all patient package subscriptions across the tenant with optional filters.

Endpoint: GET /identity/patient_package_subscriptions

Query Parameters:

Response: 200 OK

{
  "data": [
    {
      "id": "019c89f1-7a31-7637-ab47-16a0c98c4e45",
      "status": "active",
      "start_ts": "2025-01-15T10:30:00Z",
      "expiry_ts": "2026-01-15T10:30:00Z",
      "patient_id": "019c79c4-eae6-7889-a3e2-588b9a02f112",
      "patient_facility_id": "019c79c4-eb06-7157-9a0f-7a7f5146b2db",
      "service_package_id": "019c89ef-5c6b-774b-8409-a589be298ed1",
      "facility_id": "01900002-0000-7000-8000-000000000001",
      "name": "Annual Health Checkup Package",
      "duration_unit": "days",
      "duration_frequency": 365,
      "benefits_consumed": 2,
      "active": true,
      "expired": false
    }
  ],
  "meta": {
    "request_id": "uuid",
    "pagination": {
      "total_entries": 50,
      "total_pages": 2,
      "current_page": 1,
      "per_page": 25
    }
  }
}

2. Show Subscription DetailsCopy Anchor Link

Get detailed information about a specific subscription including service package details.

Endpoint: GET /identity/patient_package_subscriptions/:id

Path Parameters:

Query Parameters:

Response: 200 OK

{
  "data": {
    "id": "019c89f1-7a31-7637-ab47-16a0c98c4e45",
    "status": "active",
    "start_ts": "2025-01-15T10:30:00Z",
    "expiry_ts": "2026-01-15T10:30:00Z",
    "patient_id": "019c79c4-eae6-7889-a3e2-588b9a02f112",
    "patient_facility_id": "019c79c4-eb06-7157-9a0f-7a7f5146b2db",
    "service_package_id": "019c89ef-5c6b-774b-8409-a589be298ed1",
    "facility_id": "01900002-0000-7000-8000-000000000001",
    "name": "Annual Health Checkup Package",
    "duration_unit": "days",
    "duration_frequency": 365,
    "benefits_consumed": 2,
    "remaining_benefits": 8,
    "active": true,
    "expired": false,
    "service_package": {
      "id": "019c89ef-5c6b-774b-8409-a589be298ed1",
      "name": "Annual Health Checkup Package",
      "display_name": "Complete Health Package",
      "package_type": "health_checkup",
      "category": "wellness",
      "is_active": true,
      "total_price": 15000,
      "currency": "INR",
      "display": "Complete Health Package",
      "available": true,
      "formatted_price": "₹15,000"
    }
  },
  "meta": {
    "request_id": "uuid"
  }
}

3. List Subscriptions by Patient FacilityCopy Anchor Link

List all subscriptions for a specific patient facility.

Endpoint: GET /clinical/patient_facilities/:patient_facility_id/package_subscriptions

Path Parameters:

Query Parameters: Same as List All Subscriptions

Response: 200 OK

Same response format as List All Subscriptions.

4. List Subscriptions by PatientCopy Anchor Link

List all subscriptions for a specific patient across all facilities.

Endpoint: GET /clinical/patients/:patient_id/package_subscriptions

Path Parameters:

Query Parameters: Same as List All Subscriptions

Response: 200 OK

Same response format as List All Subscriptions.

5. List Subscriptions by Service PackageCopy Anchor Link

List all subscriptions for a specific service package.

Endpoint: GET /identity/service_packages/:service_package_id/subscriptions

Path Parameters:

Query Parameters: Same as List All Subscriptions

Response: 200 OK

Same response format as List All Subscriptions.

Data ModelsCopy Anchor Link

Subscription StatusCopy Anchor Link

Subscription Object FieldsCopy Anchor Link

Pagination ResponseCopy Anchor Link

Common Use CasesCopy Anchor Link

Get Active Subscriptions for a PatientCopy Anchor Link

GET /clinical/patients/{patient_id}/package_subscriptions?status=active&currently_active=true

Get Expired SubscriptionsCopy Anchor Link

GET /identity/patient_package_subscriptions?status=expired&include_expired=true&sort_by=expiry_ts&sort_order=desc

Get Subscriptions Near ExpiryCopy Anchor Link

GET /identity/patient_package_subscriptions?status=active&sort_by=expiry_ts&sort_order=asc

Get All Subscriptions for a FacilityCopy Anchor Link

GET /identity/patient_package_subscriptions?facility_id={facility_id}&include_expired=true

Error ResponsesCopy Anchor Link

Validation Error (422)Copy Anchor Link

{
  "success": false,
  "errors": [
    {
      "detail": "Patient facility not found"
    }
  ]
}

Not Found (404)Copy Anchor Link

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found"
  }
}

Unauthorized (401)Copy Anchor Link

{
  "error": "Unauthorized"
}

NotesCopy Anchor Link

1. Default Filtering: By default, the API excludes expired subscriptions unless include_expired=true is explicitly set.

2. Active Status: The active field in the response considers both the status field and the expiry timestamp. A subscription is active only if:

   • status is active
   • expiry_ts is null OR in the future

3. Patient Reference: The patient_id field contains a UUID reference to the patient in the clinical.patients table, but patient details are not included in the subscription response.

4. Pagination: All list endpoints support pagination. Use page and per_page parameters to navigate through results.

5. Sorting: Results can be sorted by any field in the sort_by list. Default is created_at in descending order (newest first).

Related EndpointsCopy Anchor Link

• Service Packages API: /api/identity/service_packages - Manage care package definitions
• Patient Facilities API: /api/clinical/patient_facilities - Manage patient-facility associations
• Patients API: /api/clinical/patients - Manage patient records