List catalog items
/v1/catalog/itemsLists catalog items for the authenticated account and mode. Use view=medications for priced prescription groups with offer counts, pharmacy counts, and strengths; the default view=offers returns individual offers. Use relatedToCatalogItemId to find offers for the same medication and route. When practiceId is supplied, a practice price overrides the platform price and missing overrides inherit the platform price.
Request example
curl -X GET 'https://api.affinityrx.com/v1/catalog/items' \
-H "Authorization: Bearer $AFFINITY_API_KEY" \
-H 'Affinity-Version: 2026-09-28'Response example
These examples show the body structure. Values can differ. Select a status code to see its response.
{
"data": [
{
"catalogDetails": {
"packageComponents": [
{
"container": "<string>",
"containerCount": "<string>",
"contentsPerContainer": {
"value": null,
"unit": "mg"
}
}
],
"attributes": "<string>",
"directions": [
{
"kind": "suggested",
"text": "<string>"
}
]
},
"composition": {
"status": "complete",
"ingredients": [
{
"name": "<string>",
"role": "active",
"basisOfStrengthSubstance": {
"name": "<string>"
},
"strength": {
"kind": "amount",
"amount": {
"value": null,
"unit": null
}
}
}
]
},
"allowedStates": [
"<string>"
],
"availability": "available",
"catalogKind": "<string>",
"fulfillmentInclusions": [
{
"amountCents": 0,
"kind": "cold_chain",
"label": "<string>",
"priceComponent": "shipping"
}
],
"ordering": {
"requiresPrescription": false,
"requiresAccompanyingPrescription": false,
"shipping": "prescription"
},
"category": "<string>",
"coldShip": false,
"pharmacyId": "pharm_01j2y8m6jcc9tt24af5pw9x1bc",
"pharmacyName": "<string>",
"description": "<string>",
"dosageForm": "<string>",
"facilityType": "<string>",
"id": "cat_01j2y8m6jcc9tt24af5pw9x1bc",
"imageUrl": "<string>",
"imageUrls": "<string>",
"medicationGroup": {
"offerCount": 0,
"pharmacyCount": 0,
"strengths": [
"<string>"
]
},
"isOrderable": false,
"livemode": false,
"name": "<string>",
"object": "catalog_item",
"patientSpecificRequired": false,
"quantityConstraint": {
"kind": "fixed",
"quantity": {
"value": "<string>",
"unit": "<string>"
}
},
"prescriptionRequirements": {
"allowedDaysSupply": [
0
],
"allowedQuantities": [
{
"daysSupply": 0,
"label": "<string>",
"unit": "<string>",
"value": 0
}
],
"allowedReasonCategories": [
"alcohol_free"
],
"reasonCategoryLabels": "<string>",
"compoundingReason": "not_required",
"compoundingReasonContext": "not_supported",
"controlledSchedule": "II",
"defaultDaysSupply": 0,
"defaultQuantity": {
"unit": "<string>",
"value": 0
},
"quantityIncrement": {
"max": 0,
"min": 0,
"unit": "<string>",
"value": 0
},
"defaultSigs": [
"<string>"
],
"diagnosis": "not_required",
"medicationReview": "optional",
"diagnosisReview": "optional",
"maxRefills": 0,
"notes": [
"<string>"
],
"pharmacyNotes": "not_supported",
"refills": "not_supported",
"substitution": "not_supported"
},
"pricing": {
"amountCents": "<string>",
"basis": {
"kind": "item",
"quantity": "1",
"unit": "<string>",
"quantityPrices": null
},
"currency": "USD",
"medicationSubtotalCents": "<string>"
},
"restrictedStates": [
"<string>"
],
"route": "<string>",
"shippingOptions": [
{
"amountCents": "<string>",
"carrier": "<string>",
"currency": "USD",
"destinationTypes": [
"patient"
],
"estimatedDaysMax": "<string>",
"estimatedDaysMin": "<string>",
"id": "shp_01j2y8m6jcc9tt24af5pw9x1bc",
"label": "<string>",
"serviceLevel": "<string>",
"temperatures": [
"ambient"
]
}
],
"strength": "<string>",
"unit": "<string>"
}
],
"hasMore": false,
"object": "list",
"updatedAt": "<string>",
"url": "/v1/catalog/items"
}{
"code": "<string>",
"data": "<string>",
"detail": "<string>",
"instance": "<string>",
"requestId": "<string>",
"status": 400,
"title": "<string>",
"traceId": "<string>",
"type": "<string>"
}{
"code": "<string>",
"data": "<string>",
"detail": "<string>",
"instance": "<string>",
"requestId": "<string>",
"status": 401,
"title": "<string>",
"traceId": "<string>",
"type": "<string>"
}{
"code": "<string>",
"data": "<string>",
"detail": "<string>",
"instance": "<string>",
"requestId": "<string>",
"status": 403,
"title": "<string>",
"traceId": "<string>",
"type": "<string>"
}{
"code": "<string>",
"data": "<string>",
"detail": "<string>",
"instance": "<string>",
"requestId": "<string>",
"status": 404,
"title": "<string>",
"traceId": "<string>",
"type": "<string>"
}{
"code": "<string>",
"data": "<string>",
"detail": "<string>",
"instance": "<string>",
"requestId": "<string>",
"status": 409,
"title": "<string>",
"traceId": "<string>",
"type": "<string>"
}{
"code": "<string>",
"data": "<string>",
"detail": "<string>",
"instance": "<string>",
"requestId": "<string>",
"status": 422,
"title": "<string>",
"traceId": "<string>",
"type": "<string>"
}{
"code": "<string>",
"data": "<string>",
"detail": "<string>",
"instance": "<string>",
"requestId": "<string>",
"status": 429,
"title": "<string>",
"traceId": "<string>",
"type": "<string>"
}Implementation specification
Use these field types and limits to build your integration. Download the OpenAPI document for the complete contract.
Query parameters
viewstring | nullShow schema
Any of · 1: string
string
Allowed: "offers", "medications"
Any of · 2: null
null
relatedToCatalogItemIdstring | nullShow schema
Any of · 1: string
string
Pattern: ^cat_[0-7][0-9a-hjkmnp-tv-z]{25}$
Any of · 2: null
null
catalogKindstring | nullShow schema
Any of · 1: string
string
Allowed: "prescription", "otc"
Any of · 2: null
null
sortstring | nullShow schema
Any of · 1: string
string
Allowed: "relevance", "name_asc", "name_desc"
Any of · 2: null
null
catalogItemIdstring | nullShow schema
Any of · 1: string
string
Pattern: ^cat_[0-7][0-9a-hjkmnp-tv-z]{25}$
Any of · 2: null
null
availabilitystring | nullShow schema
Any of · 1: string
string
Allowed: "all", "orderable", "unavailable"
Any of · 2: null
null
pharmacyIdsstring | string[] | nullShow schema
Any of · 1: string | string[]
Any of · 1: string
string
Pattern: ^pharm_[0-7][0-9a-hjkmnp-tv-z]{25}$
Any of · 2: string[]
Array items · string
string
Pattern: ^pharm_[0-7][0-9a-hjkmnp-tv-z]{25}$
Any of · 2: null
null
dosageFormsstring | string[] | nullShow schema
Any of · 1: string | string[]
Any of · 1: string
string
Allowed: "capsule", "cream", "gel", "solution", "spray", "tablet", "troche", "unknown", "vial"
Any of · 2: string[]
Array items · string
string
Allowed: "capsule", "cream", "gel", "solution", "spray", "tablet", "troche", "unknown", "vial"
Any of · 2: null
null
endingBeforestring | nullShow schema
Any of · 1: string
string
Pattern: ^cat_[0-7][0-9a-hjkmnp-tv-z]{25}$
Any of · 2: null
null
hideControlledSubstancesbooleanhideUnpricedbooleanlimitintegerDefault: 25
Minimum: 1
Maximum: 100
orgIdstring | nullShow schema
Any of · 1: string
string
Pattern: ^acct_[0-7][0-9a-hjkmnp-tv-z]{25}$
Any of · 2: null
null
practiceIdstring | nullShow schema
Any of · 1: string
string
Pattern: ^prac_[0-7][0-9a-hjkmnp-tv-z]{25}$
Any of · 2: null
null
querystring | nullShow schema
Any of · 1: string
string
Any of · 2: null
null
requirementstring | nullShow schema
Any of · 1: string
string
Allowed: "all", "office_use", "patient_specific"
Any of · 2: null
null
routesstring | string[] | nullShow schema
Any of · 1: string | string[]
Any of · 1: string
string
Allowed: "injectable", "nasal", "oral", "sublingual", "topical", "unknown"
Any of · 2: string[]
Array items · string
string
Allowed: "injectable", "nasal", "oral", "sublingual", "topical", "unknown"
Any of · 2: null
null
startingAfterstring | nullShow schema
Any of · 1: string
string
Pattern: ^cat_[0-7][0-9a-hjkmnp-tv-z]{25}$
Any of · 2: null
null
Headers
Affinity-VersionstringSelects the HTTP API contract for this request only. When omitted, API-key requests use their service account’s stored version. Does not change the stored default.
Pin requests to 2026-09-28.
Response specifications
200Successful response
application/json
dataobject[]requiredShow data fields
Array items · object
catalogDetailsobjectrequiredNo additional properties
Show catalogDetails fields
packageComponentsobject[] | nullConfirmed physical containers and contents. Empty or absent means container count cannot be inferred from dispense quantity.
Show packageComponents fields
Any of · 1: object[]
Array items · object
containeranyrequiredShow container fields
All of · 1: any
any
Minimum length: 1
containerCountanyrequiredShow containerCount fields
All of · 1: any
any
Greater than: 0
contentsPerContainerobjectrequiredNo additional properties
Show contentsPerContainer fields
valueany & anyrequiredShow value fields
All of · 1: any
any
Maximum length: 100
All of · 2: any
any
Pattern: ^(?:0|[1-9]\d*)(?:\.\d*[1-9])?$
unitstringrequiredAllowed: "mg", "g", "ug", "mL", "L", "[IU]", "tablet", "capsule", "troche", "actuation", "patch", "package", "container"
Any of · 2: null
null
attributesobjectrequireddirectionsobject[]requiredShow directions fields
Array items · object
kindstringrequiredAllowed: "suggested", "template"
textstringrequiredcompositionobjectrequiredNo additional properties
Show composition fields
statusstringrequiredAllowed: "complete", "partial", "unresolved"
ingredientsobject[]requiredShow ingredients fields
Array items · object
namestringrequiredrolestringrequiredAllowed: "active", "inactive"
basisOfStrengthSubstanceobject | nullrequiredShow basisOfStrengthSubstance fields
Any of · 1: object
namestringrequiredAny of · 2: null
null
strengthobjectrequiredShow strength fields
Any of · 1: object
kindstringrequiredAllowed: "amount"
amountobjectrequiredNo additional properties
Show amount fields
valueanyrequiredShow value fields
All of · 1: any
any
Pattern: ^(?:0|[1-9][0-9]*)(?:\.[0-9]+)?$
unitstringrequiredAny of · 2: object
kindstringrequiredAllowed: "ratio"
numeratorobjectrequiredNo additional properties
Show numerator fields
valueanyrequiredShow value fields
All of · 1: any
any
Pattern: ^(?:0|[1-9][0-9]*)(?:\.[0-9]+)?$
unitstringrequireddenominatorobjectrequiredNo additional properties
Show denominator fields
valueanyrequiredShow value fields
All of · 1: any
any
Pattern: ^(?:0|[1-9][0-9]*)(?:\.[0-9]+)?$
unitstringrequiredAny of · 3: object
kindstringrequiredAllowed: "unresolved"
reasonstringrequiredallowedStatesstring[]requiredShow allowedStates fields
Array items · string
string
availabilitystringrequiredAllowed: "available", "backordered", "unavailable", "unknown"
catalogKindstringrequiredfulfillmentInclusionsobject[]requiredShow fulfillmentInclusions fields
Array items · object
amountCentsintegerrequiredkindstringrequiredAllowed: "cold_chain", "injection_supplies"
labelstringrequiredpriceComponentstringrequiredAllowed: "shipping"
orderingobjectrequiredNo additional properties
Show ordering fields
requiresPrescriptionbooleanrequiredrequiresAccompanyingPrescriptionbooleanrequiredshippingstringrequiredAllowed: "prescription", "accompanying_prescription"
categorystring | nullrequiredShow category fields
Any of · 1: string
string
Any of · 2: null
null
coldShipbooleanrequiredpharmacyIdanyrequiredShow pharmacyId fields
All of · 1: any
any
Pattern: ^pharm_[0-7][0-9a-hjkmnp-tv-z]{25}$
pharmacyNamestringrequireddescriptionstringrequireddosageFormstringrequiredfacilityTypestringrequiredidanyrequiredShow id fields
All of · 1: any
any
Pattern: ^cat_[0-7][0-9a-hjkmnp-tv-z]{25}$
imageUrlstring | nullrequiredPrimary product photo, falling back to dosage-form artwork. Null when neither is available.
Show imageUrl fields
Any of · 1: string
string
Any of · 2: null
null
imageUrlsanyrequiredShow imageUrls fields
Array items · string
string
All of · 1: any
any
Maximum items: 40
medicationGroupobject | nullShow medicationGroup fields
Any of · 1: object
offerCountnumber | stringrequiredShow offerCount fields
Any of · 1: number
number
Any of · 2: string
string
Allowed: "Infinity", "-Infinity", "NaN"
pharmacyCountnumber | stringrequiredShow pharmacyCount fields
Any of · 1: number
number
Any of · 2: string
string
Allowed: "Infinity", "-Infinity", "NaN"
strengthsstring[]requiredShow strengths fields
Array items · string
string
Any of · 2: null
null
isOrderablebooleanrequiredlivemodebooleanrequirednamestringrequiredobjectstringrequiredAllowed: "catalog_item"
patientSpecificRequiredbooleanrequiredquantityConstraintobject | nullrequiredShow quantityConstraint fields
Any of · 1: object
Any of · 1: object
kindstringrequiredAllowed: "fixed"
quantityobjectrequiredNo additional properties
Show quantity fields
valueany & anyrequiredShow value fields
All of · 1: any
any
Maximum length: 100
All of · 2: any
any
Pattern: ^(?:0|[1-9]\d*)(?:\.\d*[1-9])?$
unitanyrequiredShow unit fields
All of · 1: any
any
Minimum length: 1
Any of · 2: object
kindstringrequiredAllowed: "choices"
quantitiesobject[]requiredMinimum items: 1
Show quantities fields
Array items · object
valueany & anyrequiredShow value fields
All of · 1: any
any
Maximum length: 100
All of · 2: any
any
Pattern: ^(?:0|[1-9]\d*)(?:\.\d*[1-9])?$
unitanyrequiredShow unit fields
All of · 1: any
any
Minimum length: 1
Item 1 · object
valueany & anyrequiredShow value fields
All of · 1: any
any
Maximum length: 100
All of · 2: any
any
Pattern: ^(?:0|[1-9]\d*)(?:\.\d*[1-9])?$
unitanyrequiredShow unit fields
All of · 1: any
any
Minimum length: 1
Any of · 3: object
kindstringrequiredAllowed: "range"
unitanyrequiredShow unit fields
All of · 1: any
any
Minimum length: 1
minimumany & any | nullrequiredShow minimum fields
Any of · 1: any & any
All of · 1: any
any
Maximum length: 100
All of · 2: any
any
Pattern: ^(?:0|[1-9]\d*)(?:\.\d*[1-9])?$
Any of · 2: null
null
maximumany & any | nullrequiredShow maximum fields
Any of · 1: any & any
All of · 1: any
any
Maximum length: 100
All of · 2: any
any
Pattern: ^(?:0|[1-9]\d*)(?:\.\d*[1-9])?$
Any of · 2: null
null
incrementany & any | nullrequiredShow increment fields
Any of · 1: any & any
All of · 1: any
any
Maximum length: 100
All of · 2: any
any
Pattern: ^(?:0|[1-9]\d*)(?:\.\d*[1-9])?$
Any of · 2: null
null
Any of · 4: object
kindstringrequiredAllowed: "unresolved"
sourceTextstringrequiredAny of · 2: null
null
prescriptionRequirementsobjectrequiredNo additional properties
Show prescriptionRequirements fields
allowedDaysSupplyinteger[] | nullShow allowedDaysSupply fields
Any of · 1: integer[]
Array items · integer
integer
Any of · 2: null
null
allowedQuantitiesobject[] | nullShow allowedQuantities fields
Any of · 1: object[]
Array items · object
daysSupplyinteger | nullShow daysSupply fields
Any of · 1: integer
integer
Any of · 2: null
null
labelstringrequiredunitstringrequiredvaluenumber | stringrequiredShow value fields
Any of · 1: number
number
Any of · 2: string
string
Allowed: "Infinity", "-Infinity", "NaN"
Any of · 2: null
null
allowedReasonCategoriesstring[] | nullShow allowedReasonCategories fields
Any of · 1: string[]
Array items · string
string
Allowed: "alcohol_free", "drug_shortage", "commercial_product_discontinued", "modified_release", "inactive_ingredient_sensitivity", "inactive_ingredient_toxicity", "concentration_adjustment", "alternate_route", "dosage_form_unavailable", "flavor_adjustment", "tablet_burden", "patient_cannot_use_commercial_product", "no_approved_product_available", "no_rationale_required", "other_patient_specific_need"
Any of · 2: null
null
reasonCategoryLabelsobject | nullShow reasonCategoryLabels fields
Any of · 1: object
Additional properties
string
object
Any of · 2: null
null
compoundingReasonstringrequiredAllowed: "not_required", "optional", "required"
compoundingReasonContextstring | nullShow compoundingReasonContext fields
Any of · 1: string
string
Allowed: "not_supported", "optional", "required"
Any of · 2: null
null
controlledSchedulestring | nullShow controlledSchedule fields
Any of · 1: string
string
Allowed: "II", "III", "IV", "V"
Any of · 2: null
null
defaultDaysSupplyinteger | nullShow defaultDaysSupply fields
Any of · 1: integer
integer
Any of · 2: null
null
defaultQuantityobject | nullShow defaultQuantity fields
Any of · 1: object
unitstringrequiredvaluenumber | stringrequiredShow value fields
Any of · 1: number
number
Any of · 2: string
string
Allowed: "Infinity", "-Infinity", "NaN"
Any of · 2: null
null
quantityIncrementobject | nullShow quantityIncrement fields
Any of · 1: object
maxnumber | string | nullShow max fields
Any of · 1: number | string
Any of · 1: number
number
Any of · 2: string
string
Allowed: "Infinity", "-Infinity", "NaN"
Any of · 2: null
null
minnumber | string | nullShow min fields
Any of · 1: number | string
Any of · 1: number
number
Any of · 2: string
string
Allowed: "Infinity", "-Infinity", "NaN"
Any of · 2: null
null
unitstringrequiredvaluenumber | stringrequiredShow value fields
Any of · 1: number
number
Any of · 2: string
string
Allowed: "Infinity", "-Infinity", "NaN"
Any of · 2: null
null
defaultSigsstring[] | nullShow defaultSigs fields
Any of · 1: string[]
Array items · string
string
Any of · 2: null
null
diagnosisstringrequiredAllowed: "not_required", "optional", "required"
medicationReviewstring | nullShow medicationReview fields
Any of · 1: string
string
Allowed: "optional", "required"
Any of · 2: null
null
diagnosisReviewstring | nullShow diagnosisReview fields
Any of · 1: string
string
Allowed: "optional", "required"
Any of · 2: null
null
maxRefillsinteger | nullShow maxRefills fields
Any of · 1: integer
integer
Any of · 2: null
null
notesstring[] | nullShow notes fields
Any of · 1: string[]
Array items · string
string
Any of · 2: null
null
pharmacyNotesstringrequiredAllowed: "not_supported", "optional"
refillsstringrequiredAllowed: "not_supported", "optional"
substitutionstringrequiredAllowed: "not_supported", "optional"
pricingobject | nullrequiredShow pricing fields
Any of · 1: object
amountCentsanyrequiredShow amountCents fields
All of · 1: any
any
Minimum: 0
basisobjectrequiredShow basis fields
Any of · 1: object
kindstringrequiredAllowed: "item"
quantitystringrequiredAllowed: "1"
unitanyrequiredShow unit fields
All of · 1: any
any
Minimum length: 1
quantityPricesany | nullShow quantityPrices fields
Any of · 1: any
Array items · object
quantityany & anyrequiredShow quantity fields
All of · 1: any
any
Maximum length: 100
All of · 2: any
any
Pattern: ^(?:0|[1-9]\d*)(?:\.\d*[1-9])?$
amountCentsanyrequiredShow amountCents fields
All of · 1: any
any
Greater than: 0
All of · 1: any
any
Minimum items: 1
Any of · 2: null
null
Any of · 2: object
kindstringrequiredAllowed: "package"
quantityany & anyrequiredShow quantity fields
All of · 1: any
any
Maximum length: 100
All of · 2: any
any
Pattern: ^(?:0|[1-9]\d*)(?:\.\d*[1-9])?$
unitanyrequiredShow unit fields
All of · 1: any
any
Minimum length: 1
Any of · 3: object
kindstringrequiredAllowed: "unit"
quantitystringrequiredAllowed: "1"
unitanyrequiredShow unit fields
All of · 1: any
any
Minimum length: 1
currencystringrequiredAllowed: "USD"
medicationSubtotalCentsanyrequiredShow medicationSubtotalCents fields
All of · 1: any
any
Minimum: 0
Any of · 2: null
null
restrictedStatesstring[]requiredShow restrictedStates fields
Array items · string
string
routestringrequiredshippingOptionsobject[]requiredShow shippingOptions fields
Array items · object
amountCentsanyrequiredShow amountCents fields
All of · 1: any
any
Minimum: 0
carrierstring | nullrequiredShow carrier fields
Any of · 1: string
string
Any of · 2: null
null
currencystringrequiredAllowed: "USD"
destinationTypesstring[]requiredShow destinationTypes fields
Array items · string
string
Allowed: "patient", "practice"
estimatedDaysMaxany | nullrequiredShow estimatedDaysMax fields
Any of · 1: any
All of · 1: any
any
Minimum: 0
Any of · 2: null
null
estimatedDaysMinany | nullrequiredShow estimatedDaysMin fields
Any of · 1: any
All of · 1: any
any
Minimum: 0
Any of · 2: null
null
idanyrequiredShow id fields
All of · 1: any
any
Pattern: ^shp_[0-7][0-9a-hjkmnp-tv-z]{25}$
labelstringrequiredserviceLevelstringrequiredtemperaturesstring[]requiredShow temperatures fields
Array items · string
string
Allowed: "ambient", "refrigerated"
strengthstring | nullrequiredShow strength fields
Any of · 1: string
string
Any of · 2: null
null
unitstring | nullrequiredShow unit fields
Any of · 1: string
string
Any of · 2: null
null
hasMorebooleanrequiredobjectstringrequiredAllowed: "list"
updatedAtstringrequiredurlstringrequiredAllowed: "/v1/catalog/items"
400HTTP 400
application/json
codestringrequireddataobjectdetailstringrequiredinstancestringrequiredrequestIdstringrequiredstatusintegerrequiredMinimum: 400
Maximum: 599
titlestringrequiredtraceIdstringtypestringrequiredFormat: uri
401Unauthorized
application/json
codestringrequireddataobjectdetailstringrequiredinstancestringrequiredrequestIdstringrequiredstatusintegerrequiredMinimum: 400
Maximum: 599
titlestringrequiredtraceIdstringtypestringrequiredFormat: uri
403Forbidden
application/json
codestringrequireddataobjectdetailstringrequiredinstancestringrequiredrequestIdstringrequiredstatusintegerrequiredMinimum: 400
Maximum: 599
titlestringrequiredtraceIdstringtypestringrequiredFormat: uri
404Not found
application/json
codestringrequireddataobjectdetailstringrequiredinstancestringrequiredrequestIdstringrequiredstatusintegerrequiredMinimum: 400
Maximum: 599
titlestringrequiredtraceIdstringtypestringrequiredFormat: uri
409Conflict
application/json
codestringrequireddataobjectdetailstringrequiredinstancestringrequiredrequestIdstringrequiredstatusintegerrequiredMinimum: 400
Maximum: 599
titlestringrequiredtraceIdstringtypestringrequiredFormat: uri
422Validation error
application/json
codestringrequireddataobjectdetailstringrequiredinstancestringrequiredrequestIdstringrequiredstatusintegerrequiredMinimum: 400
Maximum: 599
titlestringrequiredtraceIdstringtypestringrequiredFormat: uri
429Too many requests
application/json
codestringrequireddataobjectdetailstringrequiredinstancestringrequiredrequestIdstringrequiredstatusintegerrequiredMinimum: 400
Maximum: 599
titlestringrequiredtraceIdstringtypestringrequiredFormat: uri