Skip to main content

Dispensing events

The dispensing.* events fire whenever a dispensation changes state at the pharmacy. Most useful when:

  • Your product issued the authorization or prescription but the pharmacy is a different integrator — you want to know when it's been redeemed.
  • You're tracking real-time inventory and need to know the moment stock has left the shelf.
  • You need to reconcile completed dispensations against your local claims-in-flight.

Event types​

event_typeWhen it fires
dispensing.startedA pharmacy called startDispensation against a code your provider owns.
dispensing.completedA dispensation your provider issued was redeemed.
dispensing.cancelledA started dispensation was voided (pharmacy cancel, timeout).

dispensing.started​

Fires when a pharmacy starts a dispensation using an authorization or prescription code your provider originally issued.

{
  "event_type": "dispensing.started",
  "data": {
    "dispensation_id": "dsp_01HXDN...",
    "code": "AUTH-2026-001234",
    "code_type": "AUTHORIZATION",   // or "PRESCRIPTION"
    "beneficiary_id": "bnf_...",
    "sponsor_slug": "sponsor-sandbox",
    "pharmacy": {
      "provider_slug": "pharmacy-x",
      "branch_id": "branch_01HX..."
    },
    "products": [{ "product_code": "MED-042", "quantity": 30 }],
    "started_at": "2026-06-25T14:20:00Z"
  }
}

What to do: (optional) mark the local code as "in-flight" to prevent your UI from showing it as still-redeemable.

dispensing.completed​

The most useful event of the three. Fires the moment a dispensation succeeds.

{
  "event_type": "dispensing.completed",
  "data": {
    "dispensation_id": "dsp_01HXDN...",
    "code": "AUTH-2026-001234",
    "code_type": "AUTHORIZATION",
    "authorization_id": "auth_01HXA...",
    "prescription_id": null,             // present when code_type = PRESCRIPTION
    "beneficiary_id": "bnf_...",
    "sponsor_slug": "sponsor-sandbox",
    "pharmacy": {
      "provider_slug": "pharmacy-x",
      "branch_id": "branch_01HX..."
    },
    "products": [
      { "product_code": "MED-042", "quantity": 30, "unit_price": 12.50 }
    ],
    "total_amount": 375.00,
    "currency": "USD",
    "dispensed_at": "2026-06-25T14:22:00Z"
  }
}

What to do: mark the authorization / prescription as redeemed; kick off any claim / settlement work; notify the doctor if your product surfaces dispensation status.

dispensing.cancelled​

Fires when a STARTED dispensation is voided — either explicitly (pharmacy cancels) or by timeout.

{
  "event_type": "dispensing.cancelled",
  "data": {
    "dispensation_id": "dsp_01HXDN...",
    "code": "AUTH-2026-001234",
    "cancelled_at": "2026-06-25T14:25:00Z",
    "reason": "TIMEOUT"   // or "PHARMACY_VOID"
  }
}

What to do: revert any "in-flight" marker you set on dispensing.started. The code is redeemable again.

Multi-branch reconciliation​

The pharmacy.provider_slug and pharmacy.branch_id let you attribute a completed dispensation to a specific branch. If your integration spans multiple pharmacies, key your reconciliation off these fields, not off sponsor_slug (multiple pharmacies share the same sponsor).