API Reference

Discounts

This API provides endpoints for managing discounts. Discounts can be created, updated, and deleted. They can also be activated or deactivated. Discounts can be filtered by provider, payer, and status.

Retrieve all discounts

URL: /api/v1/providers/<provider_id>/finance/discounts

Method: GET

Request:

Query parameters:

  • search: Value should be applicable_payer's name (An organization's name)
  • is_active: A boolean value indicating whether to only return active discounts.
  • code: A unique string value
  • discount_type
  • applies_to
  • applicable_payer
  • start_datetime__gte
  • `end_datetime__lte

Response:

The response body will contain a list of discount objects, each with the following properties:

  • id: The unique identifier of the discount
  • discounted_healthcare_services: A list of healthcare services associated with the discount
  • uuid: The universally unique identifier of the discount
  • code: The discount code
  • provider: The id of the provider that issued the discount
  • applicable_payer: The id of the payer that is eligible for the discount
  • applies_to: A list of strings indicating whether the discount applies to services or invoices
  • amount: The amount of the discount
  • start_datetime: The start date of the discount
  • end_datetime: The end date of the discount
  • is_active: Whether the discount is active
  • discount_type: The type of discount (percentage or currency)
  • description: A description of the discount
  • created_at: The date and time the discount was created
  • modified_at: The date and time the discount was last modified

Example:

{
    "success": true,
    "message": "Operation successful",
    "meta": {
        "current": 1,
        "page_size_query": "page_size",
        "next": null,
        "previous": null,
        "page_size": 50,
        "total": 1
    },
    "data": [
        {
            "id": 5,
            "discounted_healthcare_services": [
                {
                    "id": "bd763fba-ac02-4399-b955-a2f0fc918e34",
                    "uuid": "ff0420a3-f0b5-4167-a381-8662d72f8799",
                    "name": "GP Consultation"
                }
            ],
            "uuid": "4aef1029-5a6d-4fdb-8cfe-1e4f169d1bb2",
            "created_at": "2023-06-15T19:17:37.044245Z",
            "is_deleted": false,
            "modified_at": "2023-06-15T19:17:37.044268Z",
            "code": "DISC001",
            "applies_to": "healthcare_service",
            "amount": "50.00",
            "start_datetime": "2023-06-16T10:00:00Z",
            "end_datetime": "2023-06-30T23:59:59Z",
            "is_active": true,
            "discount_type": "percentage",
            "description": "Example discount 1",
            "currency": "USD",
            "provider": "161380e9-22d3-4627-a97f-0f918ce3e4a9",
            "applicable_payer": "f5bd0cde-8c74-4fd7-80fa-c16e75b7427d"
        }
    ]
}

GET discounts applicable to a healthcare service

URL: /api/v1/providers/<provider_id>/healthcare-services/<healthcare_service_id>/discounts

Method: GET

Path Paremeters:

healthcare_service_id - An ID of a healthcare service object

Query parameters:

  • applicable_payer_name: applicable_payer's name (An organization's name).

Response:

The response body will contain a list of discount objects, each with the following properties

  • id: The unique identifier of the discount
  • uuid: The universally unique identifier of the discount
  • code: The discount code
  • provider: The id of the provider that issued the discount
  • applicable_payer: The id of the payer that is eligible for the discount
  • applies_to: A list of strings indicating whether the discount applies to services or invoices
  • amount: The amount of the discount
  • start_datetime: The start date of the discount
  • end_datetime: The end date of the discount
  • is_active: Whether the discount is active
  • discount_type: The type of discount (percentage or currency)
  • description: A description of the discount

Example :

{
    "success": true,
    "message": "Operation successful",
    "meta": {
        "current": 1,
        "page_size_query": "page_size",
        "next": null,
        "previous": null,
        "page_size": 50,
        "total": 4
    },
    "data": [
        {
            "id": 25,
            "uuid": "4923c67d-9b96-4653-b155-9738f5030210",
            "created_at": "2023-07-05T10:21:28.929120Z",
            "is_deleted": false,
            "modified_at": "2023-07-05T10:21:28.929129Z",
            "code": "DIS677",
            "applies_to": "healthcare_service",
            "amount": "200.00",
            "start_datetime": "2023-07-06T00:00:00Z",
            "end_datetime": "2023-07-27T00:00:00Z",
            "is_active": true,
            "discount_type": "currency",
            "description": null,
            "currency": "GHS",
            "provider": "161380e9-22d3-4627-a97f-0f918ce3e4a9",
            "applicable_payer": "d6606c01-157f-429e-bd4b-8c2b671b5131"
        },
       ...
        
    ]
}

Create a new discount

URL: /api/v1/providers/<provider_id>/finance/discounts

Method: POST

Request:

The request body must contain the following data:

  • code (required): The discount code
  • provider (required): The name of the provider that issued the discount
  • applicable_payer (required): The name of the payer that is eligible for the discount
  • applies_to (required): A list of strings indicating whether the discount applies to services or invoices
  • amount (required): The amount of the discount
  • start_datetime (required): The start date of the discount
  • end_datetime (required): The end date of the discount
  • is_active (optional, default: true): Whether the discount is active
  • discount_type (required): The type of discount (percentage or currency)
  • description (optional): A description of the discount
  • healthcare_service_ids (optional, depends on applies_to ): An array of healthcare service IDs if applies_to isservice
  • currency (optional)

Response:

The response body will contain the discount object that was created, with the following additional properties:

  • id: The unique identifier of the discount

  • uuid: The universally unique identifier of the discount

  • created_at: The date and time the discount was created

  • modified_at: The date and time the discount was last modified

Example:

{
    "code": "DISC002",
    "provider": "161380e9-22d3-4627-a97f-0f918ce3e4a9",
    "applicable_payer": "f5bd0cde-8c74-4fd7-80fa-c16e75b7427d",
    "applies_to": "healthcare_service",
    "amount": 100,
    "start_datetime": "2023-06-21T10:00:00Z",
    "end_datetime": "2023-06-30T23:59:59Z",
    "discount_type": "currency",
    "description": "Example discount 2",
    "healthcare_service_ids": ["d2983b2c-efe0-4173-85c4-cd245dd1b94d", "73f6f16f-5ebb-4a45-a614-162b2bd15fd6"],
    "currency": "GHS"
}

{
  "id": 1,
  "uuid": "123e4567-e89b-12d3-a456-426655440000",
  "code": "DISCOUNT123",
  "provider": 2,
  "applicable_payer": 9,
  "applies_to": ["service", "invoice"],
  "amount": 10,
  "start_datetime": "2023-05-01T00:00:00",
  "end_datetime": "2023-06-01T00:00:00",
  "is_active": true,
  "discount_type": "PCT",
  "description": "10% discount on all services",
  "created_at": "2023-05-15T15:22:07.000Z",
  "modified_at": "2023-05-15T15:22:07.000Z"
}

Deactivate or Activate discount

Note: A discount can only be re-activated if it hasn't expired as determined by the start_datetime and end_datetime

URL: /api/v1/providers/<provider_id>/finance/discounts/<discount_uuid>/activate

Method: PATCH

Path parameters:

  • discount_uuid: A uuid value of a discount object.

Request:

The request body must contain the following data:

  • is_active: Whether the discount should be activated or deactivated

Response:

The response body will contain the discount object with the updated is_active property.

Example response:

{
    "success": true,
    "message": "Successfully updated the activation status of the discount",
    "data": {
        "id": 5,
        "discounted_healthcare_services": [
            {
                "id": "bd763fba-ac02-4399-b955-a2f0fc918e34",
                "uuid": "ff0420a3-f0b5-4167-a381-8662d72f8799",
                "name": "GP Consultation"
            }
        ],
        "uuid": "4aef1029-5a6d-4fdb-8cfe-1e4f169d1bb2",
        "created_at": "2023-06-15T19:17:37.044245Z",
        "is_deleted": false,
        "modified_at": "2023-06-15T19:17:37.044268Z",
        "code": "DISC001",
        "applies_to": "healthcare_service",
        "amount": "50.00",
        "start_datetime": "2023-06-16T10:00:00Z",
        "end_datetime": "2023-06-30T23:59:59Z",
        "is_active": false,
        "discount_type": "percentage",
        "description": "Example discount 1",
        "currency": "USD",
        "provider": "161380e9-22d3-4627-a97f-0f918ce3e4a9",
        "applicable_payer": "f5bd0cde-8c74-4fd7-80fa-c16e75b7427d"
    },
    "errors": null
}

Receive Payment for ChargeItem(s)

URL: /api/v1/providers/<provider_id>/finance/receive-payment

Method: POST

Request:

The request body must contain the following data:

  • patient: The uuid identifier of the patient
  • charge_items: An array of charge item IDs
  • payment_info: Payment information object
    • transaction_type: The type of transaction (e.g., "insurance", "cash")
    • account_id: The uuid identifier of the account for payment
    • copayment_info: Copayment information object (optional)
      • amount: The copayment amount
      • currency: The currency of the copayment amount
      • transaction_type: The type of transaction for the copayment (e.g., "cash")
  • location: The uuid identifier of the location
  • discounted_charge_items: An array of discount objects (optional)
    • charge_item_uuid: The uuid identifier of the charge item to which a discount is applied
    • discount_uuid: The uuid identifier of an applied discount

Example:

{
    "patient": "986f4755-4e87-4090-a0b8-0ab0bb14fe4c",
    "charge_items": [
        500472,
        500450,
        500451,
        500449,
        500448
    ],
    "payment_info": {
        "transaction_type": "insurance",
        "account_id": "980360fc-192b-46dc-932e-cae3a8399f1a",
        "copayment_info": {
            "amount": "74.30",
            "currency": "GHS",
            "transaction_type": "cash"
        }
    },
    "location": "a79ae42b-03b7-4f5e-ac1a-cd42729c0b04",
    "discounted_charge_items": [
        {
            "charge_item_uuid": "<charge-item-uuid>",
            "discount_uuid": "123e4567-e89b-12d3-a456-426655440000"
        }
    ]
}

Pay for an invoice

URL: /api/v1/providers/<provider_id>/finance/invoices/<invoice_uuid>/pay

Method: POST

Request:

The request body must contain the following data:

  • account_id: The uuid identifier of the account used for payment (corporate, insurance, or patient account)
  • transaction_type: The type of transaction for payment (e.g., "user-account")
  • amount: The payment amount (required if transaction_type is cash)
  • currency: The currency of the payment amount (required if transaction_type is cash)
  • copayment_info: Copayment information object (optional)
    • account_id: The uuid identifier of the account for copayment (corporate or patient account)
    • transaction_type: The type of transaction for the copayment (e.g., "user-account")
    • amount: The copayment amount (required if transaction_type is cash)
    • currency: The currency of the copayment amount (required if transaction_type is cash)
  • location: The uuid identifier of the location
  • discount_id: The uuid identifier of the applied discount (optional)

Response:

The response body will contain the payment details and the updated invoice information.

Example:

{
   "account_id": "3173c1e1-571b-4196-8cdf-743970c67153",
   "transaction_type": "user-account",
   "amount": 200,
   "currency": "GHS",
   "copayment_info": {
     "account_id": "3173c1e1-571b-4196-8cdf-743970c67153",
     "transaction_type": "user-account",
     "amount": 200,
     "currency": "GHS"
   },
  "location": "location id",
  "discount_id": "123e4567-e89b-12d3-a456-426655440000"
}