Pharmacy Integration Guide
Photon is a prescription routing network that enables patient choice of pharmacy. Photon works with pharmacies to make sure they can reliably receive and process prescriptions.
For pharmacies, Photon does three things:
- Routes prescriptions to you when a patient or prescriber selects your pharmacy.
- Provides a reliable fallback if electronic delivery fails (so you still get the prescription).
- Supports order status updates back to Photon so patients and providers can track fulfillment.
This guide explains how delivery works and how to integrate.
Questions or special workflows? Email us at [email protected].
Sending Prescriptions
Photon delivers prescriptions to pharmacies in two ways:
- Electronic (eRx): sent electronically either as a direct NCPDP SCRIPT transmission, or via a pharmacy’s proprietary API.
- Fax + secure link: a fax notification plus secure web portal to verify.
How delivery works: Photon tries eRx first. If eRx can’t be delivered for any reason, Photon automatically falls back to fax to ensure the pharmacy receives the prescription.
Not integrated yet? If a pharmacy is not yet directly integrated with Photon (or one of our network partners), Photon defaults to a fax notification. Every fax includes a unique secure link to the original electronic prescription record for verification.
Service Availability
The Photon network is operational 24/7 and we aim to maintain very very high uptime. Downtime occurs only for scheduled maintenance and failures attributable to systems, networks, or components outside of Photon’s reasonable control, including a receiving pharmacy system.
Direct Integration
To integrate directly with Photon, your pharmacy needs an endpoint that can receive electronic prescriptions (NCPDP SCRIPT or your proprietary API).
Once you’re integrated:
- Photon will deliver prescriptions to your endpoint via eRx whenever a patient or prescriber selects your pharmacy in Photon.
- If eRx can’t be delivered, Photon will fall back to fax + secure link (so you still receive the order).
You can see example prescription payloads below.
If you’re a retail chain or mail-order pharmacy that already receives NCPDP SCRIPT prescriptions, Photon can typically handle most of the integration work. We’ll just need a technical point of contact for scoping and testing before going live.
If you’re ready to get started with Photon or have questions about an integration, reach out at [email protected].
NCPDP Transmission: Cancel & New
Photon supports NCPDP SCRIPT 2017071 and 2023011 for NewRx and CancelRx.
- CancelRx applies to a single medication. If a prescription includes multiple medications, a CancelRx message cancels only the specified medication. The others remain active unless canceled separately.
- CancelRx can’t reverse a completed fill. If a medication has already shipped or been dispensed, the cancellation will be rejected.
If your pharmacy sends a CancelRx response (approved/denied), note that Photon does not currently act on that response (for example, by automatically retrying or escalating). If you need to confirm whether a cancellation was received, reach out at [email protected].
Status Updates
If your pharmacy is able to share status updates, we have an endpoint.
POST https://api.photon.health/v1/hooks/pharmacy
{
"status": "shipped",
"order_id": "1234",
"carrier": "USPS",
"tracking_number": "5678"
}Below are statuses that we accept. If you have a status that we're not tracking let us know!
| Status | Description |
|---|---|
| new/received | The prescription (or order) has been received |
| in_progress | The prescription (or order) has begun processing |
| shipped/out_for_delivery | The prescription (or order) has been sent out for delivery (either by mail or courier) |
| completed | The prescription (or order) has been fully completed. This should only be sent once it has been shipped, picked up, or delivered |
| canceled | The prescription (or order) has been canceled |
| error | Something went wrong while filling the prescription |
For shipped/out_for_delivery, we also support passing specific shipping information. This is helpful to eliminate communication from the patient/provider.
Prescription Format
Photon typically sends prescriptions in NCPDP SCRIPT Standard format in XML or JSON. We also support modifying the message for specific use cases, such as adding IDs for your internal usage.
<Message DatatypesVersion="20170715" TransportVersion="20170715" TransactionDomain="SCRIPT"
TransactionVersion="20170715" StructuresVersion="20170715" ECLVersion="20170715">
<Header>
<To Qualifier="P">123456</To>
<From Qualifier="D">0</From>
<MessageID>01H4PG3723PGB5BVJGNR3BAB0Z</MessageID>
<SentTime>2023-07-06T21:00:30.998Z</SentTime>
<Security>
<Sender>
<TertiaryIdentification>000</TertiaryIdentification>
</Sender>
<Receiver>
<TertiaryIdentification>142</TertiaryIdentification>
</Receiver>
</Security>
<SenderSoftware>
<SenderSoftwareDeveloper>Photon Health</SenderSoftwareDeveloper>
<SenderSoftwareProduct>Photon</SenderSoftwareProduct>
<SenderSoftwareVersionRelease>1.0</SenderSoftwareVersionRelease>
</SenderSoftware>
<PrescriberOrderNumber>01H4PG3723PGB5BVJGNR3BAB0Z</PrescriberOrderNumber>
</Header>
<Body>
<NewRx>
<Patient>
<HumanPatient>
<Name>
<LastName>Smith</LastName>
<FirstName>John</FirstName>
</Name>
<Gender>M</Gender>
<DateOfBirth>
<Date>1999-01-01</Date>
</DateOfBirth>
<Address>
<AddressLine1>123 Main St</AddressLine1>
<City>Brooklyn</City>
<StateProvince>NY</StateProvince>
<PostalCode>11222</PostalCode>
<CountryCode>US</CountryCode>
</Address>
<CommunicationNumbers>
<PrimaryTelephone>
<Number>+13156634444</Number>
</PrimaryTelephone>
</CommunicationNumbers>
</HumanPatient>
</Patient>
<Pharmacy>
<Identification>
<NCPDPID>5930044</NCPDPID>
<NPI>1972149680</NPI>
</Identification>
<BusinessName>Your Pharmacy</BusinessName>
<Address>
<AddressLine1>123 MAIN ST</AddressLine1>
<City>NEW YORK</City>
<StateProvince>NY</StateProvince>
<PostalCode>11111</PostalCode>
<CountryCode>US</CountryCode>
</Address>
<CommunicationNumbers>
<PrimaryTelephone>
<Number>9174448383</Number>
</PrimaryTelephone>
<Fax>
<Number>9174448383</Number>
</Fax>
</CommunicationNumbers>
</Pharmacy>
<Prescriber>
<NonVeterinarian>
<Identification>
<NPI>123</NPI>
</Identification>
<PracticeLocation>
<BusinessName>org_U3ofDUVRsNTYt7d8</BusinessName>
</PracticeLocation>
<Name>
<LastName>Johnson</LastName>
<FirstName>John</FirstName>
</Name>
<Address>
<AddressLine1>199 N 8th St. #3B </AddressLine1>
<City>Brooklyn</City>
<StateProvince>NY</StateProvince>
<PostalCode>11211</PostalCode>
<CountryCode>US</CountryCode>
</Address>
<CommunicationNumbers>
<PrimaryTelephone>
<Number>3174504573</Number>
</PrimaryTelephone>
</CommunicationNumbers>
</NonVeterinarian>
</Prescriber>
<MedicationPrescribed>
<DrugDescription>Azelex 20 % Topical Cream</DrugDescription>
<DrugCoded>
<ProductCode>
<Code>00023-8694</Code>
<Qualifier>ND</Qualifier>
</ProductCode>
</DrugCoded>
<Quantity>
<Value>1</Value>
<CodeListQualifier>38</CodeListQualifier>
<QuantityUnitOfMeasure>
<Code>C64933</Code>
</QuantityUnitOfMeasure>
</Quantity>
<WrittenDate>
<DateTime>2023-07-06T21:00:26.844000Z</DateTime>
</WrittenDate>
<Substitutions>0</Substitutions>
<NumberOfRefills>0</NumberOfRefills>
<Note>Please provide instructions in spanish if possible</Note>
<Sig>
<SigText>Apply as needed</SigText>
</Sig>
</MedicationPrescribed>
</NewRx>
</Body>
</Message>{
"Message": {
"Header": {
"To": 123456,
"From": 0,
"MessageID": "01H4PG3723PGB5BVJGNR3BAB0Z",
"SentTime": "2023-07-06T21:00:30.998Z",
"Security": {
"Sender": {
"TertiaryIdentification": 0
},
"Receiver": {
"TertiaryIdentification": 142
}
},
"SenderSoftware": {
"SenderSoftwareDeveloper": "Photon Health",
"SenderSoftwareProduct": "Photon",
"SenderSoftwareVersionRelease": 1
},
"PrescriberOrderNumber": "01H4PG3723PGB5BVJGNR3BAB0Z"
},
"Body": {
"NewRx": {
"Patient": {
"HumanPatient": {
"Name": {
"LastName": "Smith",
"FirstName": "John"
},
"Gender": "M",
"DateOfBirth": {
"Date": "1999-01-01"
},
"Address": {
"AddressLine1": "123 Main St",
"City": "Brooklyn",
"StateProvince": "NY",
"PostalCode": 11222,
"CountryCode": "US"
},
"CommunicationNumbers": {
"PrimaryTelephone": {
"Number": 13156634444
}
}
}
},
"Pharmacy": {
"Identification": {
"NCPDPID": 5930044,
"NPI": 1972149680
},
"BusinessName": "Your Pharmacy",
"Address": {
"AddressLine1": "123 MAIN ST",
"City": "NEW YORK",
"StateProvince": "NY",
"PostalCode": 11111,
"CountryCode": "US"
},
"CommunicationNumbers": {
"PrimaryTelephone": {
"Number": 9174448383
},
"Fax": {
"Number": 9174448383
}
}
},
"Prescriber": {
"NonVeterinarian": {
"Identification": {
"NPI": 123
},
"PracticeLocation": {
"BusinessName": "org_U3ofDUVRsNTYt7d8"
},
"Name": {
"LastName": "Johnson",
"FirstName": "John"
},
"Address": {
"AddressLine1": "199 N 8th St. #3B",
"City": "Brooklyn",
"StateProvince": "NY",
"PostalCode": 11211,
"CountryCode": "US"
},
"CommunicationNumbers": {
"PrimaryTelephone": {
"Number": 3174504573
}
}
}
},
"MedicationPrescribed": {
"DrugDescription": "Azelex 20 % Topical Cream",
"DrugCoded": {
"ProductCode": {
"Code": "00023-8694",
"Qualifier": "ND"
}
},
"Quantity": {
"Value": 1,
"CodeListQualifier": 38,
"QuantityUnitOfMeasure": {
"Code": "C64933"
}
},
"WrittenDate": {
"DateTime": "2023-07-06T21:00:26.844000Z"
},
"Substitutions": 0,
"NumberOfRefills": 0,
"Note": "Please provide instructions in spanish if possible",
"Sig": {
"SigText": "Apply as needed"
}
}
}
}
}
}CancelRx
A cancellation references the original prescription via RelatesToMessageID, which matches the MessageID of the NewRx being canceled. The PrescriberOrderNumber stays the same as the original — this is how you correlate a CancelRx to a specific prescription you already have on file.
<Message DatatypesVersion="20170715" TransportVersion="20170715" TransactionDomain="SCRIPT"
TransactionVersion="20170715" StructuresVersion="20170715" ECLVersion="20170715">
<Header>
<To Qualifier="P">123456</To>
<From Qualifier="D">0</From>
<MessageID>01H4PG9F02QYX6K1MZTC4RJN8W</MessageID>
<RelatesToMessageID>01H4PG3723PGB5BVJGNR3BAB0Z</RelatesToMessageID>
<SentTime>2023-07-10T14:12:05.221Z</SentTime>
<Security>
<Sender>
<TertiaryIdentification>000</TertiaryIdentification>
</Sender>
<Receiver>
<TertiaryIdentification>142</TertiaryIdentification>
</Receiver>
</Security>
<SenderSoftware>
<SenderSoftwareDeveloper>Photon Health</SenderSoftwareDeveloper>
<SenderSoftwareProduct>Photon</SenderSoftwareProduct>
<SenderSoftwareVersionRelease>1.0</SenderSoftwareVersionRelease>
</SenderSoftware>
<PrescriberOrderNumber>01H4PG3723PGB5BVJGNR3BAB0Z</PrescriberOrderNumber>
</Header>
<Body>
<CancelRx>
<Patient>
<HumanPatient>
<Name>
<LastName>Smith</LastName>
<FirstName>John</FirstName>
</Name>
</HumanPatient>
</Patient>
<Pharmacy>
<Identification>
<NCPDPID>5930044</NCPDPID>
<NPI>1972149680</NPI>
</Identification>
</Pharmacy>
<MedicationPrescribed>
<DrugDescription>Azelex 20 % Topical Cream</DrugDescription>
<DrugCoded>
<ProductCode>
<Code>00023-8694</Code>
<Qualifier>ND</Qualifier>
</ProductCode>
</DrugCoded>
</MedicationPrescribed>
</CancelRx>
</Body>
</Message>{
"Message": {
"Header": {
"To": 123456,
"From": 0,
"MessageID": "01H4PG9F02QYX6K1MZTC4RJN8W",
"RelatesToMessageID": "01H4PG3723PGB5BVJGNR3BAB0Z",
"SentTime": "2023-07-10T14:12:05.221Z",
"PrescriberOrderNumber": "01H4PG3723PGB5BVJGNR3BAB0Z"
},
"Body": {
"CancelRx": {
"Patient": {
"HumanPatient": {
"Name": {
"LastName": "Smith",
"FirstName": "John"
}
}
},
"Pharmacy": {
"Identification": {
"NCPDPID": 5930044,
"NPI": 1972149680
}
},
"MedicationPrescribed": {
"DrugDescription": "Azelex 20 % Topical Cream",
"DrugCoded": {
"ProductCode": {
"Code": "00023-8694",
"Qualifier": "ND"
}
}
}
}
}
}
}