A compounding reason records why a compounded medication is appropriate for a patient.
Each prescription can include a reason in clinical.compoundingReason, using an Affinity category and patient-specific context where required.
Affinity translates supported categories to each pharmacy’s format.
For SDK methods, typed constants, and order examples, see Compounding reasons in TypeScript.
Categories and patient-specific context
The category identifies the reason, such as a concentration adjustment or an inactive ingredient sensitivity. Context contains the clinician’s explanation for the individual patient.
The clinician must select the applicable reason. Medication defaults do not establish the patient’s clinical need. Do not infer a diagnosis or patient-specific explanation from the selected medication. A category alone does not replace a required patient-specific explanation.
Available reason categories
Send one of these string values as clinical.compoundingReason.category.
This is the complete Affinity list. Offer only the subset returned in the selected medication’s choices, using its returned labels.
Context requirements also come from those medication options.
| API string value | Reason |
|---|---|
alcohol_free |
Alcohol-free formulation |
drug_shortage |
Documented drug shortage or backorder |
commercial_product_discontinued |
Commercial product discontinued |
modified_release |
Modified release |
inactive_ingredient_sensitivity |
Inactive ingredient sensitivity or allergy |
inactive_ingredient_toxicity |
Inactive ingredient toxicity |
concentration_adjustment |
Concentration adjustment |
alternate_route |
Alternate administration route |
dosage_form_unavailable |
Dosage form unavailable |
flavor_adjustment |
Flavor adjustment |
tablet_burden |
Reduce tablet burden |
patient_cannot_use_commercial_product |
Patient cannot use the commercial product |
no_approved_product_available |
No approved product available |
no_rationale_required |
No rationale category required |
other_patient_specific_need |
Other patient-specific need |
For example, a category-only reason uses this prescription field:
{
"clinical": {
"compoundingReason": {
"category": "concentration_adjustment"
}
}
}Add the clinician’s context when required. For text-only pharmacies, omit category and provide the explanation in context.
See TypeScript constants and string values for the SDK equivalents.
Medication requirements
The prescribing-options response includes compoundingReason requirements for the selected medication.
Offer only the accepted categories in that response.
| Field | Meaning |
|---|---|
required |
Whether the prescription needs a compounding reason. |
categoryRequired |
Whether the category must be supplied. An optional reason still needs an accepted category when the user supplies one. |
context |
required, optional, or not_supported. |
contextPrompt |
The explanation to request when the pharmacy accepts text. |
choices |
The accepted categories, with display labels. |
choices[].category |
A typed Affinity category that can be submitted without conversion. |
choices[].contextRequired |
Whether the selected choice needs a patient-specific explanation. |
choices[].contextPrompt |
The question to show for that choice. |
Use choices to populate the reason selector. Show the selected choice’s context prompt when available.
If choices is empty and context supports text, show an explanation field without a selector.
If both are unavailable, hide the reason fields.
Load options again when the medication changes. Supply expectedRevision during preview to detect changed requirements or defaults.
Pharmacy formats
| Pharmacy requirement | What to collect | What Affinity sends |
|---|---|---|
| Category only, such as PerfectRx | An accepted Affinity category | The mapped pharmacy enum |
| Category and context, such as Pharmetika-backed pharmacies | An accepted category and the required patient-specific explanation | The mapped category and supplied context |
| Text only | The clinician’s explanation | The supplied explanation |
Follow the selected medication’s requirements. Do not assume every pharmacy accepts every Affinity category.
Vendor codes such as PerfectRx’s CONC_ADJUST are not valid Affinity categories.
Affinity does not invent patient facts or a clinical rationale.
Omit the entire compoundingReason object when an optional reason is unused.
An empty string does not satisfy required context.
Validation and review
Preview returns field issues when a required category or explanation is missing, or the medication does not accept the category. Display those issues and let the clinician correct the input. Creation and signing recheck current requirements.
Do not automatically replace an unsupported category with other_patient_specific_need or no_rationale_required.
Reusing a previous prescription does not establish a current clinical rationale.
Creating an order leaves it unsigned. Signing requires the clinician’s attestation and the exact prescription versions. See Prescription defaults and previews for default resolution and the TypeScript walkthrough for implementation.