Truepill logo
Docs
Introduction
Pharmacy
Telehealth

Fulfillment API

Introduction

The fulfillment API will allow you to efficiently get medications to your patient's door across all 50 states. We take the compliance and complexity of the process off your plate so you can focus on your patient experience.

With a focus on compliance and patient safety, our process puts your patients first, every step of the way. In this section, you will explore the concepts of a patient, prescription and fill request which are the three essential components of our fulfillment API.

decorative - spacing only

Patient

Overview

The Truepill ecosystem begins by creating a patient record. It is the unifying object across our entire platform, and the entire patient journey revolves around the patient object. Patients have prescriptions and orders. Our mission is to build patient-first technology, so how could we start anywhere else?

Create a Patient

The /patient endpoint creates a patient record and returns a patient_token for you to reference in subsequent API requests that require this field.

icon code

Create patient request


const body = {
  first_name: 'Bruce',
  last_name: 'Banner',
  guardian: 'John',
  gender: 'male',
  dob: '19691218',
  street1: '123 Some Lane',
  street2: 'Apt. 123',
  city: 'Los Angeles',
  state: 'CA',
  country: 'US',
  zip: '94402',
  phone: '430-304-3949',
  email: 'hulkout@hulk.com' ,
  language_preference: 'English',
  viewed_notice_of_privacy_practices: true,
  viewed_notice_of_privacy_practices_date: '20220101'
}

fetch('https://api.truepill.com/v1/patient', {
  method: 'PUT',
  headers: {
    Authorization: 'ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(body)
})
  .then(response => response.json())
  .then(response => console.log(response))

icon success

Success response


{
  "patient_token": "4526d90a"
}

Patient API reference »

Prescription

Overview

A valid prescription is required to dispense and ship medications to your patient. There are three different ways for Truepill to obtain a valid prescription described below. Depending on your specific use case, you can navigate down to the appropriate section for your pharmacy fulfillment needs. Each of the solutions below results in a valid prescription in our pharmacy and a prescription object created in our system tied to your patient.

Electronic Prescription
A licensed US provider sends an electronic prescription or eRX (from within an EMR) into a Truepill pharmacy. This can be one of your own providers, one of ours, or a third-party provider.

Transfer Prescription
Your patient has a valid prescription at another pharmacy (i.e. Walgreens, CVS) and you provide instructions to Truepill to obtain and transfer this prescription in our pharmacy.

Direct Transfer Prescription
You have your own dispensing or non-dispensing pharmacy and want Truepill to ship medications to your patient. This is a programmatic option to transfer a prescription from your pharmacy to ours.
‍‍

Electronic prescription

An electronic prescription (eRx) is the computer-based electronic generation, transmission and filing of a prescription. In the US, the accepted standard for eRx is the “SCRIPT standard,” governed by the National Council for Prescription Drug Programs (NCPDP). A licensed US provider sends an electronic prescription or eRX (from within a EMR) into a Truepill pharmacy. This can be one of your own providers, one of ours or a third-party provider.

Diagram showing a healthcare provider writing a prescription to Truepill


Matching a prescription to your patient


Matching the incoming electronic prescription is handled by our matching engine using relevant patient, prescription and provider identifiers. Once the prescription has been successfully matched to your patient, we generate a prescription_token, which is a unique identifier for the prescription object.

icon Notify_Rx webhook success

Prescription notify event


{
  "timestamp": 1581019462,
  "callback_type": "NOTIFY_RX",
  "details": {
    "medication_name": "Atorvastatin 40 mg tablet",
    "prescriber": "Dr. Strange",
    "prescription_token": "z3q2jr",
    "patient_token": "4526d90a",
    "transfer_prescription_token": "z3q2jr23",
    "location": "Hayward, CA"
  }
}

Prescription notify API reference »

Licensed US providers can find the Truepill pharmacies from any EMR tool they use by searching by pharmacy name or pharmacy NPI. Alternatively, you can also use Truepill’s programmable EMR to send electronic prescriptions to our pharmacies.


Transfer prescription

Overview
Your patient has a valid prescription at another pharmacy (eg. Walgreens, CVS) and you provide instructions to Truepill to obtain and transfer this prescription in our pharmacy.

Diagram of transferring a prescription from a retail pharmacy


In the Truepill API, the prescription transfer is initiated by you on behalf of your patient, who has opted in to receiving their prescription via a home delivery option like Truepill. Once the prescription has been transferred, you receive a webhook event notifying you of a prescription(s) successfully transferred into our pharmacy.

Pharmacy-to-pharmacy transfers are a manual process behind the scenes involving faxes and phone calls. Although the process is entirely automated from our end, a transfer typically takes one to three business days for a pharmacy to respond and transfer a prescription.

In the Truepill API, the prescription transfer is initiated by you on behalf of your patient, who has opted in to receiving their prescription via a home delivery option like Truepill. Once the prescription has been transferred, you receive a webhook event notifying you of a prescription(s) successfully transferred into our pharmacy.

Transfer request
A transfer request can be created using our /transfer_request API endpoint. Truepill will provide a receipt confirmation of the request, but please note the subsequent webhook event notifying you of a successful transfer may take up to one to three days.

icon code

Create a transfer request


const body = {
  patient_token: '4526d90a',
  pharmacy_name: 'Walmart Pharmacy',
  pharmacy_phone: '(949) 837-0504',
  pharmacy_fax: '(949) 837-0504',
  medication_name: ['Finasteride, 1 mg', 'Sucralfate'],
  metadata: 'cfe146',
  notes: 'transfer notes'
}

fetch('https://api.truepill.com/v1/transfer_request', {
  method: 'POST',
  headers: {
    Authorization: 'ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(body)
})
  .then(response => response.json())
  .then(response => console.log(response))
icon success

Success response


{
  "request_id": "transfer_request_68e47e32ba93db638259",
  "timestamp": 1564608647,
  "status": "success",
  "details": {
    "message": "Your transfer request has been received.",
    "transfer_token": "d36889c10dcf",
    "transfer_medications": [
      {
        "transfer_medication_token": "1bbda354e8c7",
        "medication_name": "Finasteride, 1 mg"
      },
      {
        "transfer_medication_token": "ea52a1392697",
        "medication_name": "Sucralfate"
      }
    ],
    "patient_token": "4526d90a"
  }
}
icon webhook success

Success webhook event


{
  "request_id": "transfer_request_9a813a5a8782d15923da",
  "timestamp": 1564611968,
  "callback_type": "TRANSFER",
  "status": "success",
  "details": {
    "metadata": "cfe146",
    "message": "Here is a list of medications that were successfully transferred",
    "patient_token": "4526d90a",
    "medications": [
      {
        "transfer_medication_token": "6c34dacasdeb49",
        "requested_medication_name": "Bupropion XL",
        "last_filled_date": "No Data",
        "prescription_token": "z3q2jr",
        "prescriber": "Dr. P. Scribe",
        "medication_name": "Bupropion Hcl Xl 300 Mg Tablet",
        "medication_sig": "Take one daily.",
        "num_refills_remaining": 1,
        "quantity": 150,
        "days_supply": 30,
        "dea_schedule": 0
      }
    ]
  }
}
icon webhook success

Failed webhook event


{
  "request_id": "transfer_request_c91f2af0a847271bdc0b",
  "status": "error",
  "callback_type": "TRANSFER",
  "timestamp": 1502304584,
  "details": {
    "metadata": "cfe146",
    "message": "No medications were able to be transferred",
    "patient_token": "4526d90a"
  }
}
icon Notify_Rx

Prescription notify event


{
 "timestamp": 1590784899,
 "callback_type": "NOTIFY_RX",
 "details": {
   "medication_name": "Bupropion Hcl Xl 300 Mg Tablet",
   "prescriber": "Dr. P. Scribe",
   "prescription_token": "z3q2jr",
   "patient_token": "4526d90a",
   "patient_token_duplicates": [],
   "location": "hayward"
 }
}

There are a number of reasons why a transfer request may fail. These reasons include (1) patient does not have a valid prescription on file at the pharmacy, (2) patient has no refills remaining on prescription, (3) a controlled substance that cannot be transferred by state Board of Pharmacy laws.

Transfer request API reference »


Transfer a prescription from a provider
As you can see above the two fields we require for a pharmacy-to-pharmacy transfer are the name and phone number of the pharmacy. Alternatively, you can also “transfer” a prescription from a doctor's office. This means instead of reaching out to the pharmacy, Truepill will reach out to the patient’s doctor to request a new prescription to Truepill. In this scenario, you would pass in the provider’s name and phone number into the transfer request.


Direct transfer prescription

Overview
A direct transfer is a pharmacy-to-pharmacy transfer of the prescription between your pharmacy and a Truepill pharmacy. This method works best for customers that operate their own pharmacies and are looking for a programmatic way to transfer a prescription. This approach does however require a digital copy of the original prescription. And similar to a traditional transfer request, there are required fields related to the pharmacist transferring out the prescription, and the pharmacist transferring in the prescription.

Diagram showing a transfer between your pharmacy and Truepill


Transfers vs direct transfers
In the Truepill ecosystem, transfers and direct transfers are two different flows albeit sharing certain similarities. A key difference is that a direct transfer is used when you own or operate the pharmacy that holds the prescription. Thus, think of a direct transfer as a programmatic transfer of a prescription between two trusted pharmacy entities - your pharmacy and ours.

Your pharmacy is still responsible for manually deactivating the prescription upon successful direct transfer. We recommend following the same policies and procedures used for translational transfers from your pharmacy.

Direct transfers
A direct transfer request can be created using our /direct_transfer API endpoint. Truepill will provide a receipt confirmation of the request, and a subsequent webhook event once the prescription has been saved into our Truepill pharmacy system.

icon code

Create a direct transfer


const body = {
  prescriber: {
    first_name: 'Stephen',
    last_name: 'Strange',
    npi: '123123123',
    prescriber_type: 'OD',
    address: {
      name: 'Stephen Strange Practice',
      street1: '123 Some Lane',
      city: 'San Mateo',
      state: 'CA',
      zip: '94538'
    }
  },
  patient_token: '4526d90a',
  transfer_from: {
    name: 'Walmart Pharmacy',
    address: {
      name: 'Walmart Pharmacy',
      street1: '123 Some Lane',
      city: 'San Mateo',
      state: 'CA',
      zip: '94538'
    },
    id_number: '490382308',
    pharmacist: 'Dr. Storm'
  },
  transfer_to: {
    name: 'Truepill',
    id_number: '1295182590',
    pharmacist: 'Quynh Do'
  },
  prescription: {
    medication_name: 'Finasteride',
    prescribed_ndc: '12345678912',
    days_supply: 30,
    quantity_written: '60',
    quantity_dispensed: '60',
    medication_sig: 'Apply Daily.',
    written_date: '20190101',
    expiration_date: '20191231',
    last_fill_date: '20190201',
    first_fill_date: '20190115',
    fills_left: 5,
    fills_transferred: 5,
    number: '4567',
    can_substitute: true,
    direct_transfer_url:
      'https://user:securelogin@www.assets.com/rx/saijhofiasjfoasoi2f.png',
    icd10_code: 'G43.909',
    notes: 'A note here',
    diagnosis: 'Male pattern baldness'
  },
  metadata: '5fc6c6'
}

fetch('https://api.truepill.com/v1/direct_transfer', {
  method: 'POST',
  headers: {
    Authorization: 'ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(body)
})
  .then(response => response.json())
  .then(response => console.log(response))
icon success

Success response


{
  "request_id": "5a9a79a446f5d554",
  "timestamp": 1559580965,
  "status": "success",
  "details": {
    "direct_transfer_id": "c8a73a55dc"
  }
}
icon webhook success

Success webhook event


{
  "request_id": "9a813a5a8782d15923da",
  "timestamp": 1564611968,
  "callback_type": "DIRECT_TRANSFER",
  "status": "success",
  "details": {
    "metadata": "cfe146",
    "message": "Direct Transfer Accepted.",
    "patient_token": "4526d90a",
    "direct_transfer_token": "dff0a98124",
    "prescription_token": "z3q2jr"
  }
}
icon webhook success

Failed webhook event


{
  "request_id": "c91f2af0a847271bdc0b",
  "status": "error",
  "callback_type": "DIRECT_TRANSFER",
  "timestamp": 1502304584,
  "details": {
    "metadata": "cfe146",
    "message": "Direct Transfer Rejected.  duplicate",
    "patient_token": "4526d90a",
    "direct_transfer_token": "9e6d606fva"
  }
}

Direct transfer API reference »


Open refill transfer File (ORTF)

Truepill can also support the industry standard open refill transfer file (ORTF) format. Most pharmacy point-of-sale systems will provide a version of the ORTF file format to transfer data between pharmacies and systems. Due to the slight differences between each ORTF file format across different systems, we don’t offer a public-facing API for this transfer method at this time. We can support this transfer format by working directly with your team.

Our transfer processes are based on the NCPDP Prescription Transfer Standard developed for the purpose of electronically transferring prescriptions between pharmacies. We comply with legal requirements that are federal and state based. Additionally, it is up to the sender (you) and receiver (us) to follow the applicable requirements.

A note about transferring controlled substances
State and federal regulations determine requirements for controlled substances. Transfer of a drug that is both state-controlled and federally controlled will be handled in accordance with whichever regulations are more stringent.

If moving prescriptions in one pharmacy from one internal computer system to another internal computer system (for example, an in-store upgrade), state regulations for transfers are not applicable as this is not a prescription transfer. Similarly, we are able to transfer controlled substance prescriptions between our pharmacies. If transferring from one pharmacy (you or a third party pharmacy) to Truepill, the transfer is subject to state and federal regulations.

Both parties also need to take into account how individual states may vary in their classification of controlled substances. What may be considered a Schedule 2 drug in one state may be considered a Schedule 3 in another state. It is the responsibility of the sending (you) and receiving pharmacies (us) to determine what rules apply.

Fill request

Overview

Now that you have a patient token and prescription token, it’s time to create a fill request. Think of fill requests as orders within the Truepill ecosystem where a medication refill is dispensed and delivered to your patient. A fill request can be created using our Fill Request API endpoint. Truepill will provide a receipt confirmation of the request, and several subsequent webhook events throughout the lifecycle of the order.

Conceptually, a fill request is just a set of instructions you are providing to Truepill related to a patient order. In addition to the product(s) being dispensed you will also provide details like shipping address, custom packaging requirements, OTC bundled products, and anything else needed to achieve your desired patient experience.

Create a Fill Request

A fill request can be created using our /fill_request API endpoint. Truepill will provide a receipt confirmation of the request, and multiple subsequent webhook events throughout the lifecycle of your order.

Fill request API reference »

icon code

Create a fill request


const body = {
  patient_token: '4526d90a',
  patient_payment_type: 'insurance',
  insurances: [
    {
      insurance_token: '19sienglo92831n5'
    },
    {
      cardholder_id: '112233445566',
      rx_bin: '172020',
      pcn: 'HDMI',
      rx_group: '444555'
    }
  ],
  medications: [
    {
      prescription_token: 'z3q2jr'
    },
    {
      prescription_token: '3cs873'
    }
  ],
  otc_products: [
    {
      sku: 'EXAMPLESKU001',
      quantity: 30
    }
  ],
  address_to_name: 'Bruce Banner',
  address_to_company: 'Avengers',
  address_to_street1: '1700 S Amphlett Blvd',
  address_to_street2: '#221',
  address_to_city: 'San Mateo',
  address_to_state: 'CA',
  address_to_zip: '94402',
  address_to_country: 'US',
  address_to_phone: '(347) 610-8896',
  address_to_email: 'bruce.banner@avengers.com',
  shipping_method: 'usps_priority',
  signature_confirmation: false,
  replacement_order: 'fill_request_cb619ca2e133d37daefc',
  metadata: 'cfe146',
  notes: 'Here are some special instructions on how to package this order',
  patient_survey: {
    medications: 'Tafluprost',
    allergies: 'Penicillin',
    conditions: 'Glaucoma'
  }
}

fetch('https://api.truepill.com/v1/fill_request', {
  method: 'POST',
  headers: {
    Authorization: 'ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(body)
})
  .then(response => response.json())
  .then(response => console.log(response))
icon success

Success response


{
  "request_id": "fill_request_bd6825a9d66a49b3d7a7",
  "timestamp": 1592183925,
  "status": "success",
  "details": {
    "message": "Your fill request has been processed successfully.",
    "metadata": "cfe146"
  }
}

Our pharmacy fulfillment platform provides you full visibility into the status of all your orders. Thus, you will receive webhook events relating to the status of your order. Here’s a high level summary of four key webhook events in the fill request process:

  1. Order success and shipping label generated
  2. Order shipped
  3. Order in-transit
  4. Order delivered
It’s common to receive multiple shipment webhook events in the same order the updates are provided by the carrier.
icon webhook success

Success webhook event


// note that this completed order has one medication that was unable to be filled
{
 "request_id": "fill_request_0fbbde7492c8b024d800",
 "timestamp": 1571251314,
 "callback_type": "ORDER",
 "status": "success",
 "details": {
   "metadata": "cfe146",
   "message": "Your fill request was processed and is pending shipment.",
   "date_filled": "Mon, 01 Jun 2020 17:45:06 GMT",
   "order_token": "b392d",
   "medications": [
     {
       "quantity": 14,
       "medication_name": "Metronidazole 500 mg oral tablet",
       "dispensed_medication_name": "Metronidazole 500 mg oral tablet",
       "days_supply": 7,
       "requested_medication_name": "Metronidazole 500 mg oral tablet",
       "medication_token": "310ca0fa",
       "remaining_refills": {
         "total_remaining_refills": 0,
         "total_quantity_remaining": 0
       },
       "fill_number": "0",
       "rx_number": "1484947",
       "total_refills_allowed": 3,
       "prescription_token": "z3q2jr",
       "patient_cash_amount": null
     },
     {
       "quantity": 14,
       "medication_name": "Nitrofurantoin macrocrystals-monohydrate 100 mg oral capsule",
       "dispensed_medication_name": "Nitrofurantoin macrocrystals-monohydrate 100 mg oral capsule",
       "days_supply": 7,
       "requested_medication_name": "Nitrofurantoin macrocrystals-monohydrate 100 mg oral capsule",
       "medication_token": "5d466090",
       "remaining_refills": {
         "total_remaining_refills": 0,
         "total_quantity_remaining": 0
       },
       "fill_number": "0",
       "rx_number": "1483253",
       "total_refills_allowed": 3,
       "prescription_token": "3cs873",
       "patient_cash_amount": null
     },
     {
       "requested_medication_name": "Fluconazole 150 mg oral tablet",
       "reject_reason": "Refill too soon",
       "medication_token": "7ebc894e"
     }
   ],
   "tracking_url": "https://tools.usps.com/go/TrackConfirmAction_input?origTrackNum=92001902453595000012688153",
   "location": "Hayward, CA",
   "patient_token": "4526d90a"
 }
}
icon webhook success

Success webhook event


{
 "request_id": "fill_request_991e90fa6b367cf72032",
 "timestamp": 1590800102,
 "callback_type": "SHIPMENT",
 "status": "success",
 "details": {
   "metadata": "cfe146",
   "status": "TRANSIT",
   "message": "Your shipment has arrived at the USPS regional origin facility.",
   "eta": "2020-06-02T00:54:31.838Z",
   "tracking_number": "43904456187100000000000000",
   "tracking_url": "https://tools.usps.com/go/TrackConfirmAction_input?origTrackNum=43904456187100000000000000"
 }
}
icon webhook success

Success webhook event


{
 "request_id": "fill_request_991e90fa6b367cf72032",
 "timestamp": 1590800162,
 "callback_type": "SHIPMENT",
 "status": "success",
 "details": {
   "metadata": "cfe146",
   "status": "TRANSIT",
   "message": "In Transit, Arriving On Time",
   "eta": "2020-06-02T00:54:31.838Z",
   "tracking_number": "43904456187100000000000000",
   "tracking_url": "https://tools.usps.com/go/TrackConfirmAction_input?origTrackNum=43904456187100000000000000"
 }
}
icon webhook success

Success webhook event


{
 "request_id": "fill_request_991e90fa6b367cf72032",
 "timestamp": 1590800222,
 "callback_type": "SHIPMENT",
 "status": "success",
 "details": {
   "metadata": "cfe146",
   "status": "DELIVERED",
   "message": "Your shipment has been delivered at the destination mailbox.",
   "eta": "2020-06-02T00:54:31.838Z",
   "tracking_number": "43904456187100000000000000",
   "tracking_url": "https://tools.usps.com/go/TrackConfirmAction_input?origTrackNum=43904456187100000000000000"
 }
}

There are a number of reasons why a Fill Request may be rejected by our pharmacy. The most common reasons include: (1) missing or invalid prescription (2) incorrect shipping address (3) various insurance rejection reasons.

A Fill Request will not be rejected unless all the medications are unable to be filled. It is possible to receive a successful order callback with some of the medications rejected.
icon webhook success

Failed webhook event


// No additional information required/accompanying this rejection reason
{
 "request_id": "fill_request_2c069215483bb6676a9b",
 "status": "error",
 "timestamp": 1585608018,
 "callback_type": "ORDER",
 "details": {
   "metadata": "cfe146",
   "error_code": "NR",
   "description": "Rejected: No Refills Remaining",
   "message": null,
   "order_token": "b392d",
   "medications": [
     {
       "prescription_token": "z3q2jr"
     },
     {
       "prescription_token": "3cs873"
     }
   ]
 }
}

Fill request API reference »

Refills

Overview

The only difference between a refill and a first fill is that this time around, you already have a patient_token and prescription_token – so you are all set! Just send in a fIll request and follow the same process as before and repeat this until you have no remaining refills on a given prescription.

Important note: We will always use the shipping address details as part of the fill request. This allows you to modify your shipping address details on a per-order basis without having to update your patient record. You can also update your shipping address or speed at any point during the fulfillment process up until a shipping label has been generated and sent back to you.

Managing refill quantities

Depending on whether your patients are paying for their prescriptions with cash or insurance, you have some control over the quantity of medication dispensed. For cash prescriptions, you can dispense multiple fills and custom quantities as needed. For example, let’s say you have a prescription on file for “11 refills of Atorvastatin 40mg, take 1 tablet a day.” Conceptually, you can think of this as 11 refills x 30 days/month x 1 pill/day = 330 pills. If your patient pays for 200 pills, you can specify a quantity of 30 using the quantity field as part of your fill request.

For insurance prescriptions, the payor will determine the appropriate quantity that you can dispense to the patient. Typically, this is a 30-90 day supply of medication. In the event you request a quantity greater than allowed by the patient’s insurance, we will dispense the maximum allowable limit and send the quantity_dispensed as part of your fill request webhook event.

You can submit a fill request that contains both full and partial requests.

Here is an example of a fill request and webhook event with deferring quantities.

icon code

Fill request with refill management


const body = {
  patient_token: '4526d90a',
  patient_payment_type: 'insurance',
  insurances: [
    {
      insurance_token: '19sienglo92831n5'
    }
  ],
  medications: [
    {
      prescription_token: 'z3q2jr',
      quantity: 90
    },
    {
      prescription_token: '3cs873',
      quantity: 15
    }
  ],
  address_to_name: 'Bruce Banner',
  [...other fields...]
}

fetch('https://api.truepill.com/v1/fill_request', {
  method: 'POST',
  headers: {
    Authorization: 'ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(body)
})
  .then(response => response.json())
  .then(response => console.log(response))
icon webhook success

Success webhook event


{
  "request_id": "fill_request_0fbbde7492c8b024d800",
  "timestamp": 1571251314,
  "callback_type": "ORDER",
  "status": "success",
  "details": {
    "metadata": "cfe146",
    "message": "Your fill request was processed and is pending shipment.",
    "date_filled": "Mon, 01 Jun 2020 17:45:06 GMT",
    "order_token": "b392d",
    "medications": [
      {
        "quantity": 90,
        "medication_name": "Metronidazole 500 mg oral tablet",
        "dispensed_medication_name": "Metronidazole 500 mg oral tablet",
        "days_supply": 7,
        "requested_medication_name": "Metronidazole 500 mg oral tablet",
        "medication_token": "310ca0fa",
        "dispensed_ndc": "1234567890",
        "remaining_refills": {
          "total_remaining_refills": 0,
          "total_quantity_remaining": 0
        },
        "fill_number": "0",
        "rx_number": "1484947",
        "total_refills_allowed": 3,
        "prescription_token": "z3q2jr",
        "patient_cash_amount": null
      },
      {
        "quantity": 15,
        "medication_name": "Nitrofurantoin macrocrystals-monohydrate 100 mg oral capsule",
        "dispensed_medication_name": "Nitrofurantoin macrocrystals-monohydrate 100 mg oral capsule",
        "days_supply": 7,
        "requested_medication_name": "Nitrofurantoin macrocrystals-monohydrate 100 mg oral capsule",
        "medication_token": "5d466090",
        "remaining_refills": {
          "total_remaining_refills": 0,
          "total_quantity_remaining": 0
        },
        "fill_number": "0",
        "rx_number": "1483253",
        "total_refills_allowed": 3,
        "prescription_token": "3cs873",
        "patient_cash_amount": null
      },
      {
        "requested_medication_name": "Fluconazole 150 mg oral tablet",
        "reject_reason": "Refill too soon",
        "medication_token": "7ebc894e"
      }
    ],
    "tracking_url": "https://tools.usps.com/go/TrackConfirmAction_input?origTrackNum=92001902453595000012688153",
    "tracking_number": "92001902453595000012688153",
    "carrier": "usps",
    "location": "Hayward, CA",
    "patient_token": "4526d90a"
  }
}
Important note: When dealing with insurance claim billing, it is extremely important to manage the quantity_dispensed field diligently. Understanding exactly how much medication is dispensed to your patient as part of each fill request is critical to ensuring your patients never run out of their medications.

Managing refill timing

When using our fill request API endpoint, it’s important to remember Truepill will never ship out a refill to your patient without an explicit new fill request. It is your responsibility to manage the timing of your fill requests to ensure your patients always have medications on hand. In general, we recommend issuing your next fill request 7-8 days before your patient runs out of medication. This is typically also the time window that insurance allows for billing the next refill of medication.

If you send a fill request too early for an insurance billed prescription, you will receive a “Refill Too Soon” error message from the payor, with a specific date that you can bill against insurance. Depending on your preference, we can hold this fill request until the refill too soon date arrives, or reject the fill request and await a new one sent by you after the refill too soon date passes.

Refill API reference »

Multi-dose packaging

Truepill can support a range of medication packaging types including standard vials, custom branded vials and bottles, branded single dose pouch packaging and multi-dose strip style packaging. You can specify the packaging type for your order using the medication_packaging_type field.

icon code

Fill request with multi-dose packaging


const body = {
  patient_token: '4526d90a',
  patient_payment_type: 'cash',
  medications: [
    {
      prescription_token: 'z3q2jr'
    },
    {
      prescription_token: '3cs873'
    }
  ],
  medication_packaging_type: 'standard vial',
  [...other fields...]
}

fetch('https://api.truepill.com/v1/fill_request', {
  method: 'POST',
  headers: {
    Authorization: 'ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(body)
})
  .then(response => response.json())
  .then(response => console.log(response))

Multi-dose packaging API reference »

Custom packaging

We’re here to represent your brand and customer packaging is a core part of that experience. Many customers provide their own packaging materials to our facilities. We can also design and procure custom packaging for you.

We can support a range of needs including different brand box types and styles, marketing collateral and inserts, new vs. existing customer packaging, new customer welcome letter, seasonal products and inserts, promotional and other brand materials, OTC product samples - just to name a few examples of how our partners bring their brands to life with Truepill. You can use the packaging_configuration field in the fill request API to provide specific details of your packaging process for a specific order.

icon code

Fill request with custom packaging


const body = {
  patient_token: '4526d90a',
  patient_payment_type: 'cash',
  medications: [
    {
      prescription_token: 'z3q2jr'
    },
    {
      prescription_token: '3cs873'
    }
  ],
  packaging_instructions: 'promotional Vitamin B product sample',
  [...other fields...]
}

fetch('https://api.truepill.com/v1/fill_request', {
  method: 'POST',
  headers: {
    Authorization: 'ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(body)
})
  .then(response => response.json())
  .then(response => console.log(response))

Custom packaging API reference »

Over-the-counter (OTC) products

Truepill can support a broad range of non-prescription OTC products in addition to the full formulary of prescription products. You can dispense an OTC product alone or a bundle of OTC products combined with you prescription medications. Some customers also choose to drop ship and store their OTC products in a Truepill facility for use during the pick and packing process for their orders. You can submit multiple OTC products as part of a fill request using the otc_products field.

A prescription is not required for an OTC product - you do not need to pass in a prescription_token for an order that contains only OTC products.

icon code

Fill request with OTC products


const body = {
  patient_token: '4526d90a',
  patient_payment_type: 'cash',
  otc_products: [
    {
      sku: 'EXAMPLESKU001',
      quantity: 30
    }
  ],
  [...other fields...]
}

fetch('https://api.truepill.com/v1/fill_request', {
  method: 'POST',
  headers: {
    Authorization: 'ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(body)
})
  .then(response => response.json())
  .then(response => console.log(response))

Over-the-counter (OTC) API reference »