For AI agents: the documentation index is at /docs/payerbox/llms.txt. A Markdown version of this page is available at /docs/payerbox/data-integration/carin-bb/pharmacy.md or by requesting it with the Accept: text/markdown header.
Payerbox Docs

Pharmacy

Datasets

A pharmacy claim is one dispensing event from a retail, mail-order or specialty pharmacy, adjudicated in the NCPDP telecommunication format rather than on a paper form. CARIN Blue Button STU 2.1.0 profiles it twice: the financial profile with amounts for Patient Access, and its parent Basis profile without amounts for Provider Access and Payer-to-Payer. You deliver one pair of files.

DatasetCARIN BB STU 2.1.0 target profile
claims_pharmacyC4BB ExplanationOfBenefit Pharmacy, served without amounts as Pharmacy Basis
claims_pharmacy_linesExplanationOfBenefit.item of the same profile

Both files carry every column from Explanation of Benefit. This page lists what the pharmacy profile adds and where it tightens a shared rule. A pharmacy claim almost always has one line, the drug dispensed; the split into two files is kept so every claim type has the same shape.

claims_pharmacy

One row per pharmacy claim.

Prescription

The NCPDP fields the profile requires of every pharmacy claim. Each is a supportingInfo entry tagged with its C4BBSupportingInfoType category. Four of them are mandatory, which no other claim type asks of its supporting information.

ColumnRequiredFormat / valuesExample
claim_received_dateRecommendeddate the payer received the claim2026-03-02
days_supplyYesinteger; days of medication dispensed (NCPDP 405-D5)30
daw_codeYesone character; dispense-as-written or product-selection code (NCPDP 408-D8) NCPDPDispensedAsWrittenOrProductSelectionCode0
refill_numberYesinteger; which fill this is, 0 for the original (NCPDP 403-D3)0
refills_authorizedYesinteger; refills the prescriber authorized (NCPDP 415-DF)5
brand_generic_indicatorRecommendedone character; how the plan adjudicated the drug (NCPDP 686) NCPDPBrandGenericIndicator2
rx_origin_codeRecommendedone digit; how the prescription reached the pharmacy (NCPDP 419-DJ) NCPDPPrescriptionOriginCode3
compound_codeRecommended0 not specified, 1 not a compound, 2 compound (NCPDP 406-D6) NCPDPCompoundCode1
  • days_supply, daw_code, refill_number and refills_authorized are mandatory: CARIN requires all four on every pharmacy claim, so a row missing any of them is rejected. refill_number 0 is the original fill, not a missing value.
  • compound_code decides what the line carries. 0 or 1: the line's service_code is the NDC dispensed. 2: the line's service_code is blank, and the ingredients travel in the line's compound columns.
  • The NCPDP code sets are licensed, so their value sets are linked to the IG rather than expanded here. Send the codes as your adjudication system holds them.

Care team

Bound to C4BBClaimPharmacyTeamRole, which has two roles.

ColumnRequiredFormat / valuesExample
prescribing_provider_npiRecommended10 digits; key from practitioners; who wrote the prescription9999999991
primary_provider_npiIf available10 digits; key from practitioners
  • billing_provider_npi from the shared columns is the pharmacy, an organization. The profile also allows a practitioner there for the rare individually enrolled dispenser.
  • The prescriber is not the dispenser. Send the prescriber's NPI here even when the pharmacy is the billing provider; it is how a member sees who prescribed what.

Adjudication

ColumnRequiredFormat / valuesExample
benefit_payment_statusYesinnetwork, outofnetwork, other; how the claim was paid against the member's pharmacy benefit C4BBPayerBenefitPaymentStatusinnetwork
billing_network_statusRecommendedinnetwork, outofnetwork; whether the pharmacy had a contract with the plan on the fill date C4BBPayerProviderNetworkStatusinnetwork
  • benefit_payment_status sits on the claim row, as on the institutional claims. Pharmacy has no claim-level adjustment reasons: a rejected claim carries its NCPDP reject code on the line.
  • payment_date from the shared columns is must-support here. Send it whenever the claim was paid.
  • No diagnosis columns. The pharmacy profile does not ask for diagnoses, and NCPDP claims rarely carry them.

Amounts

The shared amount columns on the claim row become the claim totals, which are mandatory: at least one must be filled. The pharmacy profile has no claim-level adjudication amounts; line amounts are mandatory, see below. drug_cost_amount is the ingredient cost and is the one category that exists for pharmacy claims first; send it separately from eligible_amount, which includes the dispensing fee.

Set by Payerbox

ElementValue
typepharmacy
useclaim
meta.profilethe Pharmacy canonical with version 2.1.0
identifier.typeuc
insurance.focaltrue on the coverage from coverage_id
item.productOrServicethe literal compound when compound_code is 2
careTeam.sequence, supportingInfo.sequence, item.detail.sequencenumbered from the columns and list positions

claims_pharmacy_lines

One row per dispensed product. In practice one per claim; a compound is still one line, with its ingredients listed on it.

ColumnRequiredFormat / valuesExample
service_codeYes, blank only for a compoundthe NDC dispensed, 11 digits with or without hyphens FDANDCOrCompound00093-1058-01
service_code_systemNohttp://hl7.org/fhir/sid/ndc is the only system here (assumed when empty)
service_date_startYesdate the prescription was filled2026-03-01
quantityRecommendeddecimal; quantity dispensed (NCPDP 442-E7)30
quantity_unitIf availableunit of the quantity: EA, GM, ML (NCPDP 600-28)EA
compound_ingredient_ndcsIf compound_code is 2NDCs of the ingredients, ;-separated FDANationalDrugCode00093-1058-01;00054-0222-20
compound_ingredient_quantitiesIf compound_code is 2decimal quantities, ;-separated, aligned with compound_ingredient_ndcs30;15
reject_reason_codeIf rejectedNCPDP reject code (NCPDP 511-FB) NCPDPRejectCode75
amount columnsYes, at least oneline-level adjudication, one column per category
  • service_code is the NDC as your system holds it. Both the 11-digit form with hyphens (00093-1058-01) and without (00093105801) are in the value set; send one form consistently.
  • A compound has no single NDC. Leave service_code blank, set compound_code 2 on the claim row, and list every ingredient with its quantity in the two compound columns; each becomes an item.detail under the line. A line with a blank service_code on a claim whose compound_code is not 2 is rejected.
  • service_date_start overrides the shared "Recommended": the fill date is mandatory, and a single date. Leave service_date_end blank.
  • reject_reason_code replaces the CARC and RARC adjustment reasons of the other claim types; the pharmacy profile allows one NCPDP reject code per line and no other reason. A rejected claim carries submitted_amount, 0.00 in benefit_amount, the rejected amount in noncovered_amount and the code here.
  • At least one amount is mandatory on every line. drug_cost_amount belongs on the line as well as in the totals.

These resources are served by Patient Access with amounts, and by Provider Access and Payer-to-Payer without them.

Last updated: