Quantities and Package Sizes

How to correctly specify what to dispense when placing an order

Getting package_size and quantity right is the single most common sticking point when placing an order via the API. This guide breaks down exactly what each field means, how they work together, and the mistakes we see most often, so you can get it right the first time.

The three fields that define an order

When you place an order via the API, you're telling us exactly what to dispense and how much. There are three fields involved:

• prescription_id — the unique ID of the prescription, provided to you in the RX_RECEIVED webhook
• package_size — how many units are in a single packed item (e.g., 60 for a 60gm cream tube)
• quantity — how many of those packed items you want sent (e.g., 2 for two tubes)

Quantity vs. package size, at a glance

Term	What it means	Example
quantity	How many separate packed items	2 tubes
package_size	How many units are in one packed item	20 grams per tube

Example: A patient needs 2 tubes of tretinoin cream, each tube is 20 grams.

package_size: 20
quantity: 2

The written quantity rule

You can never dispense more than what the prescription authorizes in total, across all orders combined. That total is calculated as:

Max dispensable = written quantity × (refills + 1)

You can split a prescription across multiple orders, using the same prescription_id each time.

Example: A prescription is written for 90 tablets with 1 refill.

• Max dispensable = 90 × (1 + 1) = 180 tablets total
• You could send half now: package_size: 90
• And the other half later, using that same prescription ID

An example request body dispensing half of a prescription of 90 tablets with 1 refill may look like the following:

{
  "shipping": {
    "method_id": 1,
  },
  "patient": {
    "patient_id": "abc123",
    "patient_safety": {
      "medications": [],
      "health_conditions": [],
      "allergies": []
    }
  },
  "items": [
    {
      "prescription_id": 123456,
      "package_size": 90
    }
  ]
}

info

This is a commonly used request payload that does not include:

• Patient information other than the patient ID
• A shipping address

In this scenario, an order will be created for the patient associated with the patient ID sent in RX_RECEIVED webhook event. We will use the shipping address provided on the prescription.

Common mistakes to avoid

❌ Treating a cream like a countable item

Creams and other topicals are measured in weight (grams) or volume (milliliters), not count. Sending package_size: 1, quantity: 28 for a cream doesn't mean "one 28gm tube", it reads as 28 separate items, each sized at 1 unit.

✅ Correct: package_size: 28, quantity: 1 (or omit both if the Rx is already written for 28gm)

❌ Leaving out the NDC when it's required

Some products (especially compounds) require a specific NDC to be included, either on the Rx itself or in the pharmacy notes field. Sending a custom NDC through the pharmacy notes has to be turned on for your account first. It's not enabled by default, so check with your Honeybee contact to get this turned on before relying on it. If it's missing or doesn't match, the order will error out.

✅ Correct: Confirm which NDC(s) are available for a product before sending, and include the matching one.

❌ Sending a quantity that doesn't match a valid package size

If quantity is sent but package_size doesn't line up with one of the product's actual available sizes, the order may dispense fewer units than expected, or fail entirely. For example, requesting quantity: 2 for a cream without a valid matching package size can result in only 1 unit being dispensed.

✅ Correct: Always check the product's available package sizes before placing the order, and make sure package_size matches one exactly.

❌ Requesting a package size that doesn't exist

If no package size exists in our system at the weight/volume or count you're requesting, you'll see an error like:

There is no package size for the written quantity: X.0 on the prescription.

✅ Correct: Check available package sizes before placing an order. If you're not sure what's available for a product, reach out to your Honeybee contact to confirm.

How this works with your integration type

How much control you have over package_size and quantity depends on which type of partner integration you're using:

Partner type	How orders work	Flexibility
Automatic Processing	Order fires automatically on Rx receipt	Less control, the order is created for the prescription as written
API Driven (Partner Requested Fills)	You POST an order referencing the Rx ID	Full control over package_size and quantity per fill
Dashboard partners	Orders placed manually via dashboard	UI-guided, no API calls needed

Quick reference: order item fields

Field	Required?	Default if omitted
prescription_id	Yes	—
package_size	Optional	Written quantity on the Rx
quantity	Optional	1
ndc	Sometimes	From the Rx, if present

Still not sure?

Reach out in your support channel or ping your Honeybee implementation contact. When in doubt, just send the prescription_id, and we'll default to the Rx as written.