> ## Documentation Index
> Fetch the complete documentation index at: https://openloop.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Events

> The signed webhook contract for clinical, lab, document, scheduling, prescription and billing state changes. One envelope, one signature scheme, one delivery policy across every event.

> [!WARNING]
>
> Webhook delivery is configured per customer; there is no self-serve subscription endpoint. Your
> OpenLoop implementation contact registers your HTTPS endpoint, selects the event types it receives,
> and returns the signing secret once. Until your endpoint is registered this page is the contract to
> build against, not a step you can complete yourself.

When delivery is enabled for your organization, OpenLoop POSTs state changes to your endpoint as
**signed webhooks** — past-tense facts you react to instead of polling. Every event — clinical,
lab, document, scheduling, prescription or billing — rides the **same envelope, the same Standard Webhooks
signature, and the same delivery policy**; they differ only by `type` and the shape of `data`.

Verify each webhook's signature before trusting it, return a `2xx` quickly, and do slower work
asynchronously.

## The envelope

The `POST` body is exactly these five top-level keys:

```json Example: prescription.shipped theme={null}
{
  "id": "4b1e9c7a2f...e9f",
  "type": "prescription.shipped",
  "eventVersion": "1.0",
  "occurredAt": "2026-10-13T16:05:12.000Z",
  "data": {
    "resource_id": "rx_01J8...",
    "patient_ref": "pat_01J8...",
    "resource_organization_id": "org_01J8...",
    "prescribed_product": { "code": "WM-SEMA-0.25", "display": "Semaglutide 0.25mg" },
    "pharmacy": "phr_01J8...",
    "status": "shipped",
    "timestamps": {
      "created_at": "2026-10-10T14:30:00.000Z",
      "ordered_at": "2026-10-11T09:12:00.000Z",
      "shipped_at": "2026-10-13T16:05:00.000Z"
    },
    "carrier": "usps",
    "tracking_ref": "9400100000000000000000",
    "charting_note_id": "60000001",
    "occurred_at": "2026-10-13T16:05:12.000Z"
  }
}
```

| Key | Value |
| - | - |
| `id` | The event's idempotency key: the SHA-256 hash of the source event's internal id, hex-encoded. It is the same value on every retry and redelivery of the same event, and is sent again as the `webhook-id` header. **Dedupe on this.** |
| `type` | The dotted event name, e.g. `prescription.shipped`. See the event types below. |
| `eventVersion` | The version of the `data` payload for this `type`, as a string (e.g. `"1.0"`, `"2.0"`). It changes when the shape of `data` changes; an endpoint is pinned to the version it registered for. |
| `occurredAt` | When the event occurred upstream (ISO-8601), not when we sent it. |
| `data` | The event payload — shape depends on `type`. See [Event payloads](#event-payloads). |

## Event types

These are the event types delivered today. An endpoint receives only the types your OpenLoop contact
subscribes it to; a subscription may be an exact type (`prescription.shipped`), a whole family
(`prescription.*`), or everything (`*`).

An endpoint is pinned to one `eventVersion` per type (see [Delivery semantics](#delivery-semantics)),
so where **Emitted today** lists more than one version, subscribe to each version you need.

| Event type | Available versions | Emitted today | Sent when |
| - | - | - | - |
| `invoice.created` | `2.0` | `2.0` | An invoice is created |
| `invoice.finalized` | `2.0` | `2.0` | An invoice is finalized and can be paid |
| `invoice.payment_succeeded` | `2.0` | `2.0` | A payment attempt on an invoice succeeds |
| `invoice.payment_failed` | `2.0` | `2.0` | A payment attempt on an invoice fails |
| `invoice.payment_action_required` | `2.0` | `2.0` | A payment on an invoice needs the customer to act, e.g. to authenticate |
| `invoice.paid` | `2.0` | `2.0` | An invoice is paid in full |
| `invoice.voided` | `2.0` | `2.0` | An invoice is voided |
| `invoice.marked_uncollectible` | `2.0` | `2.0` | An invoice is marked uncollectible |
| `subscription.created` | `2.0` | `2.0` | A subscription is created |
| `subscription.updated` | `2.0` | `2.0` | A subscription changes |
| `subscription.canceled` | `2.0` | `2.0` | A subscription is canceled |
| `subscription.paused` | `2.0` | `2.0` | A subscription's status changes to `paused` |
| `subscription.resumed` | `2.0` | `2.0` | A subscription in `paused` status resumes |
| `subscription.trial_will_end` | `2.0` | `2.0` | A trial ends in three days, or is ended now |
| `credit_note.created` | `2.0` | `2.0` | A credit note is created, e.g. by a refund |
| `credit_note.voided` | `2.0` | `2.0` | A credit note is voided |
| `dispute.created` | `2.0` | `2.0` | A customer disputes a charge |
| `dispute.updated` | `2.0` | `2.0` | A dispute changes, e.g. evidence is submitted |
| `dispute.funds_withdrawn` | `2.0` | `2.0` | The disputed funds are withdrawn |
| `dispute.funds_reinstated` | `2.0` | `2.0` | The disputed funds are returned |
| `dispute.closed` | `2.0` | `2.0` | A dispute ends: won, lost or warning closed (see `status`) |
| `checkout.session.completed` | `2.0` | `2.0` | A checkout session completes |
| `checkout.session.expired` | `2.0` | `2.0` | A checkout session expires before it completes |
| `checkout.session.async_payment_succeeded` | `2.0` | `2.0` | A delayed payment for a checkout session succeeds |
| `checkout.session.async_payment_failed` | `2.0` | `2.0` | A delayed payment for a checkout session fails |
| `intake.created` | `1.0`, `1.1`, `2.0` | `1.0` · `1.1` | A patient's intake (questionnaire response) is created |
| `intake.signed` | `1.0`, `1.1`, `2.0` | `1.0` | An intake is signed |
| `intake.completed` | `1.0`, `1.1`, `2.0` | `1.0` · `1.1` | An intake is completed (finished / locked) |
| `charting.created` | `1.0` | `1.0` (staging only) | A clinician's charting form — any form that is not an intake — is created |
| `charting.signed` | `1.0` | `1.0` (staging only) | A charting form is signed |
| `charting.completed` | `1.0` | `1.0` (staging only) | A charting form is completed (finished / locked) |
| `intake_appointment.created` | `1.0`, `2.0` | `2.0` | An intake form is linked to a new appointment |
| `intake_appointment.updated` | `1.0`, `2.0` | `2.0` | An intake-appointment link changes |
| `requested_form_completion.created` | `1.0` | `1.0` | A patient is sent a request to fill out a form |
| `requested_form_completion.updated` | `1.0` | `1.0` | The status of a form request changes: the patient opens or submits the form |
| `requested_form_completion.deleted` | `1.0` | `1.0` | A form request is deleted |
| `appointment.created` | `1.0`, `1.1`, `1.2`, `2.0` | `1.0` (clinical) · `2.0` (scheduling) | An appointment is created |
| `appointment.updated` | `1.0`, `1.1`, `1.2`, `2.0` | `1.0` (clinical) · `2.0` (scheduling) | An appointment changes |
| `appointment.deleted` | `1.0`, `1.1`, `1.2`, `2.0` | `2.0` (scheduling) | An appointment is cancelled / deleted |
| `patient.created` | `1.0` | `1.0` | A patient record is created |
| `patient.updated` | `1.0` | `1.0` | A patient record changes |
| `patient_document.created` | `1.0` | `1.0` | A document is added to a patient's record |
| `patient_document.updated` | `1.0` | `1.0` | A document on a patient's record changes |
| `prescription.created` | `1.0`, `2.0` | `1.0` | A prescription is created |
| `prescription.ordered` | `1.0`, `2.0` | `1.0` | A prescription is sent to the pharmacy |
| `prescription.shipped` | `1.0`, `2.0` | `1.0` | A prescription ships |
| `prescription.cancelled` | `1.0`, `2.0` | `1.0` | A prescription is cancelled |
| `prescription.invoiced` | `2.0` | `2.0` | A prescription is invoiced |
| `prescription.paid` | `2.0` | `2.0` | A prescription is paid |
| `prescription.refund_requested` | `2.0` | `2.0` | A refund is requested for a prescription |
| `prescription.changed` | `2.0` | `2.0` | A prescription changes |
| `lab_order.created` | `1.0` | `1.0` (by arrangement) | A lab order is placed |
| `lab_order.updated` | `1.0` | `1.0` (by arrangement) | A lab order has a later transition at the lab network |
| `lab_result.created` | `1.0` | `1.0` (by arrangement) | Results for a lab order first become available |
| `lab_result.updated` | `1.0` | `1.0` (by arrangement) | More results for a lab order become available, or become final |

> [!NOTE]
>
> Selections are expanded into concrete types when your endpoint is saved. An endpoint saved with `*`
> or a family wildcard (`lab_order.*`) before a type existed does not receive that type until its
> subscriptions are updated. Ask your OpenLoop contact to re-save the endpoint when a new type appears
> here.

> [!NOTE]
>
> `prescription.delivered` exists in the event vocabulary but is **not produced today**. Do not build
> on it.

> [!NOTE]
>
> **Lab events are delivered by arrangement.** A lab event reaches your endpoint only once OpenLoop has
> linked your lab network account to your organization; until then it is not delivered to you. Your
> OpenLoop implementation contact confirms when that link is in place.

> [!NOTE]
>
> **Payments types are `2.0` only.** Every `invoice.*`, `subscription.*`, `credit_note.*`,
> `dispute.*` and `checkout.session.*` type is delivered at `2.0`, the shape documented on this page.
> There is no `1.0` payments subscription.

## Verifying the signature

Deliveries are signed per the [Standard Webhooks](https://www.standardwebhooks.com/) spec, so
off-the-shelf verification libraries work. Each `POST` carries:

| Header | Value |
| - | - |
| `content-type` | `application/json` |
| `webhook-id` | Same value as `body.id` — the SHA-256 event id. |
| `webhook-timestamp` | Unix **seconds** at the moment of this attempt — recomputed on every retry. |
| `webhook-signature` | `v1,<base64 HMAC-SHA256>` over `<webhook-id>.<webhook-timestamp>.<raw-body>`. A single `v1,` token today — one signing secret per endpoint. |
| `openloop-environment` | The OpenLoop environment that sent the delivery: `production`, `staging` or `development`. Not covered by the signature. |

Each delivery also carries `user-agent: OpenLoop-Webhooks/1.0` and `accept-encoding: identity`.

Verifying by hand:

1. Concatenate `<webhook-id>.<webhook-timestamp>.<raw-request-body>` — the exact bytes received, before any JSON parsing.
2. Strip the `whsec_` prefix from your signing secret and base64-decode the remainder to get the key.
3. Compute `HMAC-SHA256` over the concatenated string, keyed with the decoded secret.
4. Base64-encode the result and compare it, with a constant-time comparison, against the `v1,`-prefixed token in `webhook-signature` (prefix stripped).
5. Reject a `webhook-timestamp` more than 5 minutes from your own clock, so a captured delivery can't be replayed later.

### Telling environments apart

Every delivery, test deliveries included, carries `openloop-environment`. The body and the
signature are the same in every environment, so this header is the only way to tell a staging
event from a production one when both reach the same URL.

Signing secrets are never shared across environments: an endpoint registered in staging has its own
secret, and it cannot verify a production delivery. If one URL receives more than one environment:

1. Read `openloop-environment` and pick the signing secret you were given for that environment.
2. Verify the signature with it. A delivery whose header was changed in transit fails here, because
   the secret for the claimed environment did not sign it.
3. Drop a verified delivery from an environment that URL should not serve, e.g. `staging` on your
   production handler, and still answer `2xx` so it is not retried.

The values are fixed: `production`, `staging` and `development`. Treat any other value as an
unknown environment and do not process it.

## Delivery semantics

| Behavior | Value |
| - | - |
| Guarantee | At-least-once. Dedupe on `webhook-id`. **No ordering guarantee.** |
| Success | Any `2xx`. |
| Retried | `408`, `429`, `5xx`, a response timeout, or a connection error. |
| Not retried | Every other `4xx`, and any redirect — `3xx` responses are never followed. |
| Attempts | Up to **4 attempts per delivery round**. |
| Spacing | Roughly **5 minutes** between attempts (driven by the queue's visibility timeout; not a fixed short interval). |
| Timeout | **30 seconds** per attempt. |
| After a round exhausts | The delivery is recorded as failed; it is not re-sent automatically. An OpenLoop operator can re-drive it for another round. |

Your endpoint must be `https://`, present a valid TLS ≥1.2 certificate, and resolve to a public
address — redirects are not followed and private/loopback targets are refused.

## What not to assume

* **No delivery-status or replay API.** There is no endpoint to query past deliveries, and a failed delivery is not re-sent beyond the retries above (an operator can re-drive it).
* **No ordering.** Order by `occurredAt`, and treat a `webhook-id` you have already applied as a duplicate.
* **Delivery is version-matched.** A subscription is pinned to one exact `eventVersion` and receives only events of that version. Where a `type` ships at more than one version — e.g. `intake.created` / `intake.completed` at `1.0` and `1.1`, `intake_appointment.*` at `2.0`, or the prescription billing verbs at `2.0` — subscribe to each version you need; a `1.0` subscription will not receive a `1.1` or `2.0` event. A subscription without a version gets the type's default version: `1.0` where the type has one.
* **`extra_fields` is usually a raw passthrough.** On most payloads `extra_fields` is the source record's native object and is **not part of the versioned canonical contract** — build on the canonical fields and treat it as opaque. The exceptions are documented per type below: the scheduling appointment versions (`1.1` / `1.2` / `2.0`), `intake_appointment` and `requested_form_completion` carry a defined `extra_fields` object.
* **Nullable fields can be `null` on a valid event.** A field marked nullable below is present with a `null` value when the source has nothing to put there; an absent key is not expected.
* **No self-service registration.** Your endpoint and signing secret are configured by your OpenLoop implementation contact.

## Event payloads

Each table below is the `data` object for that event type (the envelope keys `id` / `type` /
`eventVersion` / `occurredAt` are above). Event types that share a `data` shape are documented once;
the intro says what each verb sets. Every field is reproduced from the delivered schema.
**Required** means the key is always present; a **Nullable** key may carry `null`.

### Prescriptions

`prescription.created` fires when a prescription is created, `prescription.ordered` when it is sent to
the pharmacy, `prescription.shipped` when it ships (carrier/tracking typically present), and
`prescription.cancelled` when it is cancelled. `prescription.invoiced`, `prescription.paid`,
`prescription.refund_requested` and `prescription.changed` follow the prescription's billing.

The eight come from the same producer but form two groups with different shapes. The four lifecycle
verbs are emitted at `1.0` and carry the `1.0` shape; the four billing verbs are emitted at `2.0` and
carry the `2.0` shape. The two shapes differ in `patient_ref` nullability, `context` and the
`timestamps` keys (see the tabs below). Within a group, the events share one shape and differ only
in `status` and which `timestamps.*` field the event sets.

**Lifecycle, `1.0`**

| Event | `status` | Timestamp set |
| - | - | - |
| `prescription.created` | `created` | `timestamps.created_at` |
| `prescription.ordered` | `ordered` | `timestamps.ordered_at` |
| `prescription.shipped` | `shipped` | `timestamps.shipped_at` (and typically `carrier` / `tracking_ref`) |
| `prescription.cancelled` | `cancelled` | `timestamps.cancelled_at` |

**Billing, `2.0`**

| Event | `status` | Timestamp set |
| - | - | - |
| `prescription.invoiced` | `invoiced` | `timestamps.invoiced_at` |
| `prescription.paid` | `paid` | `timestamps.paid_at` |
| `prescription.refund_requested` | `refund_requested` | `timestamps.refund_requested_at` |
| `prescription.changed` | `changed` | `timestamps.changed_at` |

> [!NOTE]
>
> `timestamps.*` accumulate per order within a group: once a stage's timestamp is set for an order, it
> stays populated on every later event for that order, so a missed event loses none of that order's
> stages. One prescription (`resource_id`) can have more than one order, and each order's events carry
> only that order's timestamps. For example, a second order that is created and cancelled after the
> first one shipped sends a `prescription.cancelled` with no `ordered_at` or `shipped_at`. To show a
> prescription's progress, merge the `timestamps` of every event you received for its `resource_id`,
> keeping the first value set for each timestamp, rather than reading only the latest event. A
> `prescription.cancelled` with neither `ordered_at` nor `shipped_at` usually means that order was
> never placed: when the prescription already shipped, that shipment still stands, so don't show the
> prescription as cancelled on it. Events can also arrive out of order, so a `prescription.ordered` or
> `prescription.shipped` that arrives after a cancel wins over it. An order with more than one fill
> sends each event once per fill. `carrier` and `tracking_ref` are set by an order's first shipped
> event and don't change after it; `pharmacy` can change when an order is rerouted, so take it from
> the latest event. A `1.0` event has no billing timestamps; those arrive only on the `2.0` billing
> events.

> [tab] 1.0 (default)
>
> | Field | Type | Required | Nullable | Description |
> | - | - | - | - | - |
> | `resource_id` | string | Yes | No | Stable surrogate id of the prescription resource. |
> | `patient_ref` | string | Yes | No | Opaque reference to the patient the prescription belongs to. See [Correlating events to your records](#correlating-events-to-your-records). |
> | `emr_patient_id` | string | No | No | The patient's id, the `id` that `GET /v0.1/patients/{id}` takes, when known; omitted otherwise. |
> | `resource_organization_id` | string | Yes | Yes | Owning organization id; `null` when not attributable to an org. |
> | `prescribed_product` | object | Yes | Yes | The prescribed product, or `null` when unknown. |
> | `prescribed_product.code` | string | Yes | No | Product code (present when `prescribed_product` is set). |
> | `prescribed_product.display` | string | No | No | Human-readable product name. |
> | `pharmacy` | string | Yes | Yes | Dispensing pharmacy identifier; `null` when none assigned. |
> | `status` | string | Yes | No | Lifecycle status, one of `created`, `ordered`, `shipped`, `delivered`, `cancelled`, `unknown` (`delivered` is defined but not produced today). |
> | `timestamps` | object | Yes | No | Stage timestamp map; every sub-field is optional and accumulates as the order progresses. |
> | `timestamps.created_at` | string | No | No | When the prescription was created. |
> | `timestamps.ordered_at` | string | No | No | When it was sent to the pharmacy. |
> | `timestamps.shipped_at` | string | No | No | When it shipped. |
> | `timestamps.delivered_at` | string | No | No | When it was delivered. Defined in the schema but not produced today. |
> | `timestamps.cancelled_at` | string | No | No | When it was cancelled. |
> | `carrier` | string | No | No | Shipping carrier name (typically set at/after shipment). |
> | `tracking_ref` | string | No | No | Carrier tracking reference (typically set at/after shipment). |
> | `charting_note_id` | string | No | No | Id of the clinician's charting note the prescription was ordered from: the same id as `data.resource_id` on that note's `charting.*` events. Omitted when the prescription was not ordered from a charting note; never `null`. See [Linking a prescription to its charting note](#linking-a-prescription-to-its-charting-note). |
> | `context` | object | No | No | Free-form `string → string` metadata map. Its keys are **not part of the versioned contract** — do not depend on specific keys. |
> | `occurred_at` | string | Yes | No | When this event occurred (mirrors the envelope `occurredAt`). |

> [tab] 2.0
>
> | Field | Type | Required | Nullable | Description |
> | - | - | - | - | - |
> | `resource_id` | string | Yes | No | Stable surrogate id of the prescription resource. |
> | `patient_ref` | string | Yes | Yes | Opaque reference to the patient the prescription belongs to; `null` when not attributable. |
> | `emr_patient_id` | string | No | No | The patient's id, the `id` that `GET /v0.1/patients/{id}` takes, when known; omitted otherwise. |
> | `resource_organization_id` | string | Yes | Yes | Owning organization id; `null` when not attributable to an org. |
> | `prescribed_product` | object | Yes | Yes | The prescribed product, or `null` when unknown. |
> | `prescribed_product.code` | string | Yes | No | Product code (present when `prescribed_product` is set). |
> | `prescribed_product.display` | string | No | No | Human-readable product name. |
> | `pharmacy` | string | Yes | Yes | Dispensing pharmacy identifier; `null` when none assigned. |
> | `status` | string | Yes | No | Lifecycle status, one of `created`, `invoiced`, `paid`, `ordered`, `shipped`, `refund_requested`, `cancelled`, `changed`. |
> | `timestamps` | object | Yes | No | Stage timestamp map; every sub-field is optional and accumulates as the order progresses. |
> | `timestamps.created_at` | string | No | No | When the prescription was created. |
> | `timestamps.ordered_at` | string | No | No | When it was sent to the pharmacy. |
> | `timestamps.shipped_at` | string | No | No | When it shipped. |
> | `timestamps.cancelled_at` | string | No | No | When it was cancelled. |
> | `timestamps.invoiced_at` | string | No | No | When it was invoiced. |
> | `timestamps.paid_at` | string | No | No | When it was paid. |
> | `timestamps.refund_requested_at` | string | No | No | When a refund was requested. |
> | `timestamps.changed_at` | string | No | No | When it was changed. |
> | `carrier` | string | No | No | Shipping carrier name (typically set at/after shipment). |
> | `tracking_ref` | string | No | No | Carrier tracking reference (typically set at/after shipment). |
> | `charting_note_id` | string | No | No | Id of the clinician's charting note the prescription was ordered from: the same id as `data.resource_id` on that note's `charting.*` events. Omitted when the prescription was not ordered from a charting note; never `null`. See [Linking a prescription to its charting note](#linking-a-prescription-to-its-charting-note). |
> | `context` | object | No | No | Curated `PrescriptionContextV2` object (sub-fields below), replacing the v1 free-form map. |
> | `context.patient_state` | string | No | No | Patient US state. |
> | `context.compound_order_status` | string | No | No | Compound order status. |
> | `context.compound_paid_status` | string | No | No | Compound paid status. |
> | `context.provider_id` | string | No | No | Prescribing provider id. |
> | `context.prescription_order_id` | string | No | No | Prescription order id. |
> | `context.pharmacy_order_id` | string | No | No | Pharmacy order id. |
> | `context.pharmacy_code` | string | No | No | Pharmacy code. |
> | `context.fill` | string | No | No | Fill descriptor. |
> | `context.cancellation_reason` | string | No | No | Cancellation reason. |
> | `occurred_at` | string | Yes | No | When this event occurred (mirrors the envelope `occurredAt`). |

The four lifecycle verbs are emitted at `1.0` only; subscribing to them at `2.0` receives nothing
today. The four billing verbs exist only at `2.0`. To follow a prescription end to end, subscribe
to the lifecycle verbs at `1.0` and the billing verbs at `2.0`.

#### Linking a prescription to its charting note

`data.charting_note_id` is the clinician's charting note the prescription was ordered from. It
matches `data.resource_id` on that note's `charting.*` events, so key on it to tie the prescription
to the note. It is on every prescription event, `1.0` and `2.0`, when OpenLoop has the value, and
omitted, never `null`, when the prescription was not ordered from a charting note.

### Lab orders and results

`lab_order.created` fires once, when a lab order is placed, and `lab_order.updated` fires on every
later transition at the lab network, whether or not `status` changes. `lab_result.created` fires on the first transition that makes results
available for an order, and `lab_result.updated` on each later one, including when partial results
become final. One transition can produce both a `lab_order.updated` and a `lab_result.*` event.

Both families carry **references and status only**. No result values, analyte names, codes,
reference ranges, interpretations, documents or patient demographics ride on these events. They
tell you that something happened to an order; they do not deliver its results.

Only `1.0` exists for each type. Lab events are delivered by arrangement: they reach your endpoint
only once OpenLoop has linked your lab network account to your organization.

#### Lab orders

`lab_order.created` and `lab_order.updated` carry the same data shape. Branch on `status`, not on
the event type: `lab_order.created` is sent only at the first status, and every later transition,
including cancellation and completion, arrives as `lab_order.updated`. `status` can repeat: two
`received.*` transitions send two `lab_order.updated` events, both with `status: received`, and
`vendor_status` tells them apart.

> [tab] 1.0 (default)
>
> | Field | Type | Required | Nullable | Description |
> | - | - | - | - | - |
> | `resource_id` | string | Yes | No | Lab order id. The same value as `order_id` in the `POST /v0.1/laboratories` response. |
> | `resource_organization_id` | string | Yes | Yes | Opaque reference to the lab network account that holds the order. It is not your OpenLoop organization id. `null` when the order is not attributable. |
> | `status` | string | Yes | No | Canonical status, one of `received`, `collecting_sample`, `sample_with_lab`, `completed`, `cancelled`, `failed`, `unknown`. `unknown` is sent for a status OpenLoop does not recognise yet; handle it. |
> | `vendor_status` | string | Yes | Yes | The lab network's detailed status for the latest transition, verbatim, e.g. `received.walk_in_test.requisition_created`. Its values are not a closed set and are not part of the versioned contract: log or display it, branch on `status`. `null` when the order has no transitions. |
> | `patient_ref` | string | Yes | Yes | Always `null` today. Correlate on `resource_id` instead; see [Correlating events to your records](#correlating-events-to-your-records). |
> | `ordering_provider_ref` | string | Yes | Yes | Always `null` today. |
> | `lab_test_refs` | array | Yes | No | Ids of the lab tests on the order: zero or one today. Never `null`. |
> | `vendor_order_transaction_ref` | string | Yes | Yes | Groups an order with its redraws: an original order and its redraws share this value. |
> | `collection_method` | string | Yes | Yes | How the sample is collected, e.g. `walk_in_test`, `testkit`. |
> | `origin` | string | Yes | Yes | `initial` for a first order, `redraw` for a redraw. |
> | `ordered_at` | string | Yes | Yes | When the order was placed (ISO-8601); `null` when the order has no transitions yet. |
> | `created_at` | string | Yes | No | Creation timestamp (ISO-8601). |
> | `updated_at` | string | Yes | No | Last-update timestamp (ISO-8601). |

> [!NOTE]
>
> `status: completed` means the lab finished processing the order. Results may still be in flight on
> OpenLoop's side when the event arrives.

```json Example: lab_order.created theme={null}
{
  "id": "9c2f4d81a7...b30",
  "type": "lab_order.created",
  "eventVersion": "1.0",
  "occurredAt": "2026-10-19T14:02:11.000Z",
  "data": {
    "resource_id": "129f08c5-f3e0-4ce2-a9c1-47141ded1f3a",
    "resource_organization_id": "d5d224b8-9397-4138-acd7-6e7b41bb3259",
    "status": "received",
    "vendor_status": "received.testkit.ordered",
    "patient_ref": null,
    "ordering_provider_ref": null,
    "lab_test_refs": ["c533549c-1e62-4afe-9a0e-0567a9b2bcc2"],
    "vendor_order_transaction_ref": "d74f33be-b8c3-4001-bd28-066094f4ed05",
    "collection_method": "testkit",
    "origin": "initial",
    "ordered_at": "2026-10-19T14:02:09+00:00",
    "created_at": "2026-10-19T14:02:09+00:00",
    "updated_at": "2026-10-19T14:02:09+00:00"
  }
}
```

#### Lab results

`lab_result.created` and `lab_result.updated` carry the same data shape. A transition that does
not change result availability, such as a shipping update after results exist, sends no
`lab_result.*` event.

| Event | When | `status` |
| - | - | - |
| `lab_result.created` | The first transition with results for the order | `partial`, or `final` when the order goes straight to complete |
| `lab_result.updated` | Every later transition with results | `partial` for more partial results, `final` once complete |

Partial results are sent only when they are enabled for your lab account. Without them, an order
produces one `lab_result.created` with `status: final`.

> [tab] 1.0 (default)
>
> | Field | Type | Required | Nullable | Description |
> | - | - | - | - | - |
> | `resource_id` | string | Yes | No | Id of the result. Treat it as opaque and do not assume it equals `lab_order_ref`. |
> | `resource_organization_id` | string | Yes | Yes | Opaque reference to the lab network account that holds the order, as on `lab_order.*`. It is not your OpenLoop organization id. |
> | `lab_order_ref` | string | Yes | No | The lab order these results belong to: the `resource_id` of its `lab_order.*` events and the `order_id` from `POST /v0.1/laboratories`. **Join on this.** |
> | `patient_ref` | string | Yes | Yes | Always `null` today. |
> | `status` | string | Yes | No | `partial` or `final`. No other value is sent. |
> | `vendor_status` | string | Yes | No | The lab network's detailed status for the transition that announced the results, verbatim, e.g. `sample_with_lab.walk_in_test.partial_results`. Not part of the versioned contract: log or display it, branch on `status`. |
> | `result_event_at` | string | Yes | Yes | When the lab network recorded the transition that announced the results (ISO-8601). It is not the clinical time the report was issued. `null` when not provided. |
> | `created_at` | string | Yes | No | When the lab order was created (ISO-8601). |
> | `updated_at` | string | Yes | No | When the lab order was last updated (ISO-8601). |

```json Example: lab_result.created theme={null}
{
  "id": "e51b7a3c09...d42",
  "type": "lab_result.created",
  "eventVersion": "1.0",
  "occurredAt": "2026-10-21T18:40:27.000Z",
  "data": {
    "resource_id": "7a3e5c19-2b8d-4f60-9e1a-c4d2b6f8a013",
    "resource_organization_id": "d5d224b8-9397-4138-acd7-6e7b41bb3259",
    "lab_order_ref": "7a3e5c19-2b8d-4f60-9e1a-c4d2b6f8a013",
    "patient_ref": null,
    "status": "partial",
    "vendor_status": "sample_with_lab.walk_in_test.partial_results",
    "result_event_at": "2026-10-21T18:40:24+00:00",
    "created_at": "2026-10-20T13:15:02+00:00",
    "updated_at": "2026-10-21T18:40:24+00:00"
  }
}
```

> [!WARNING]
>
> Do not rely on receiving `lab_result.created` before `lab_result.updated`. Deliveries are not
> ordered, and if the delivery that announced the first results is lost, no `lab_result.created` is
> sent for that order. Treat a `lab_result.updated` for a `lab_order_ref` you have not seen as its
> first result, and order a lab order's events by `occurredAt`.

### Patients

`patient.created` fires when a patient record is created and `patient.updated` when one
changes; both deliver the patient's canonical demographic snapshot. These fields are PHI — handle
accordingly.

`patient.created` and `patient.updated` carry the same data shape.

> [tab] 1.0 (default)
>
> | Field | Type | Required | Nullable | Description |
> | - | - | - | - | - |
> | `resource_id` | string | Yes | No | Canonical patient id. |
> | `resource_organization_id` | string | Yes | Yes | Opaque reference to the organization that holds the record. It is not your OpenLoop organization id. `null` if unknown. |
> | `active` | boolean | Yes | Yes | Whether the patient record is active. |
> | `first_name` | string | Yes | Yes | Given name. |
> | `middle_name` | string | Yes | Yes | Second given name. |
> | `last_name` | string | Yes | Yes | Family name. |
> | `email` | string | Yes | Yes | Patient email. |
> | `phone` | string | Yes | Yes | Phone. |
> | `birth_date` | string | Yes | Yes | Date of birth. |
> | `gender` | string | Yes | Yes | Gender. |
> | `sex` | string | Yes | Yes | Sex. Always `null` today. |
> | `preferred_language` | string | Yes | Yes | Preferred language code. |
> | `addresses` | array | Yes | Yes | Canonical addresses, or `null`. |
> | `addresses[].line1` | string | Yes | Yes | Address line 1. |
> | `addresses[].line2` | string | No | Yes | Address line 2 (optional). |
> | `addresses[].city` | string | Yes | Yes | City. |
> | `addresses[].state` | string | Yes | Yes | State / region. |
> | `addresses[].postal_code` | string | Yes | Yes | Postal / ZIP code. |
> | `addresses[].country` | string | Yes | Yes | Country. |
> | `tags` | array | Yes | Yes | Canonical tags, or `null`. Always `null` today. |
> | `tags[].type` | string | Yes | Yes | Tag type / category. |
> | `tags[].name` | string | Yes | No | Tag name. |
> | `created_at` | string | Yes | Yes | Creation timestamp (ISO-8601). Always `null` today. |
> | `updated_at` | string | Yes | Yes | Last-update timestamp (ISO-8601). |
> | `extra_fields` | object | Yes | No | Passthrough — not part of the versioned contract (see note below). |

`extra_fields` is the source record's native payload; its shape varies and is not covered by
`eventVersion`.

```json patient.created theme={null}
{
  "id": "1f6a0c93e4...7d2",
  "type": "patient.created",
  "eventVersion": "1.0",
  "occurredAt": "2026-10-20T15:41:07.000Z",
  "data": {
    "resource_id": "3f2b9c1e-7a4d-4e8b-9c21-5d6e7f8a9b0c",
    "resource_organization_id": "8f3c2a1d-6b4e-4d7a-9c5f-0e2b4d6f8a1c",
    "active": true,
    "first_name": "Jane",
    "middle_name": null,
    "last_name": "Sample",
    "email": "jane.sample@example.com",
    "phone": "+15555550100",
    "birth_date": "1990-04-12",
    "gender": "female",
    "sex": null,
    "preferred_language": "en",
    "addresses": [
      {
        "line1": "100 Example St",
        "line2": null,
        "city": "Austin",
        "state": "TX",
        "postal_code": "78701",
        "country": "US"
      }
    ],
    "tags": null,
    "created_at": null,
    "updated_at": "2026-10-20T15:41:05.112Z",
    "extra_fields": { "…": "source record passthrough; not part of the contract" }
  }
}
```

```json patient.updated theme={null}
{
  "id": "8b03d5e7a1...c49",
  "type": "patient.updated",
  "eventVersion": "1.0",
  "occurredAt": "2026-10-21T09:12:44.000Z",
  "data": {
    "resource_id": "3f2b9c1e-7a4d-4e8b-9c21-5d6e7f8a9b0c",
    "resource_organization_id": "8f3c2a1d-6b4e-4d7a-9c5f-0e2b4d6f8a1c",
    "active": true,
    "first_name": "Jane",
    "middle_name": null,
    "last_name": "Sample",
    "email": "jane.sample@example.com",
    "phone": "+15555550199",
    "birth_date": "1990-04-12",
    "gender": "female",
    "sex": null,
    "preferred_language": "en",
    "addresses": [
      {
        "line1": "200 Example Ave",
        "line2": "Apt 4",
        "city": "Austin",
        "state": "TX",
        "postal_code": "78702",
        "country": "US"
      }
    ],
    "tags": null,
    "created_at": null,
    "updated_at": "2026-10-21T09:12:42.630Z",
    "extra_fields": { "…": "source record passthrough; not part of the contract" }
  }
}
```

`patient.updated` carries the full snapshot after the change, not a diff. Compare it to the record
you hold to see what changed.

### Patient documents

`patient_document.created` fires when a document is added to a patient's record and
`patient_document.updated` when its details change, e.g. its title. Both carry the document's
**metadata only**: never the file, a link to it, or its contents. `resource_id` is not a
`/v0.1/document-references` id, so the document endpoints of this API do not return it.

`patient_document.created` and `patient_document.updated` carry the same data shape. Only `1.0`
exists.

> [tab] 1.0 (default)
>
> | Field | Type | Required | Nullable | Description |
> | - | - | - | - | - |
> | `resource_id` | string | Yes | No | Document id. The same on `.created` and every later `.updated` for that document. |
> | `resource_organization_id` | string | Yes | Yes | Opaque reference to the organization that holds the record. It is not your OpenLoop organization id. |
> | `patient_ref` | string | Yes | Yes | Opaque reference to the patient the document belongs to. It is not guaranteed to be a `/v0.1` patient id; see [Correlating events to your records](#correlating-events-to-your-records). |
> | `emr_patient_id` | string | No | No | The patient's id, the `id` that `GET /v0.1/patients/{id}` takes, when known; omitted otherwise. |
> | `title` | string | Yes | Yes | The document's display name, as a user typed it. |
> | `content_type` | string | Yes | Yes | MIME type, e.g. `application/pdf`. |
> | `visible_to_patient` | boolean | Yes | Yes | `true` when the document is shared with the patient, `false` when it is not. `null` means **unknown**, not hidden: never read `null` as `false`. A change of visibility is not guaranteed to send `patient_document.updated`, so the value on the latest event you hold can be out of date. |
> | `created_at` | string | Yes | Yes | When the document was created. As the source reports it, e.g. `2026-10-20 12:03:50 -0400`: a local offset, not ISO-8601 UTC. Sharing it later does not change it. |
> | `updated_at` | string | Yes | Yes | When the document was last edited. As the source reports it, e.g. `2026-10-20 12:03:50 -0400`: a local offset, not ISO-8601 UTC. It does not move when visibility changes. |
> | `extra_fields` | object | Yes | No | A fixed set of metadata keys, below. Adding or changing one needs a new `eventVersion`. |
> | `extra_fields.extension` | string | Yes | Yes | File extension, e.g. `pdf`. |
> | `extra_fields.owner` | object | Yes | Yes | `{ "organization": { "id" } }` for the organization that owns the document, or `null`. `organization` is `null` when unknown. |
> | `extra_fields.changed_fields` | array | Yes | No | The source fields that changed, e.g. `["display_name"]` on `.updated`. Empty on `.created` in practice: it mirrors the source change, which lists none on create. |
> | `extra_fields.resourceIdType` | string | Yes | No | Always `Document`. |

```json patient_document.created theme={null}
{
  "id": "5e9d1a2b7c...04f",
  "type": "patient_document.created",
  "eventVersion": "1.0",
  "occurredAt": "2026-10-20T16:03:52.000Z",
  "data": {
    "resource_id": "48213907",
    "resource_organization_id": "102938",
    "patient_ref": "6650172",
    "title": "Intake summary.pdf",
    "content_type": "application/pdf",
    "visible_to_patient": true,
    "created_at": "2026-10-20 12:03:50 -0400",
    "updated_at": "2026-10-20 12:03:50 -0400",
    "extra_fields": {
      "extension": "pdf",
      "owner": { "organization": { "id": "102938" } },
      "changed_fields": [],
      "resourceIdType": "Document"
    }
  }
}
```

```json patient_document.updated theme={null}
{
  "id": "c27f80e4d9...a61",
  "type": "patient_document.updated",
  "eventVersion": "1.0",
  "occurredAt": "2026-10-20T16:20:14.000Z",
  "data": {
    "resource_id": "48213907",
    "resource_organization_id": "102938",
    "patient_ref": "6650172",
    "title": "Intake summary - signed.pdf",
    "content_type": "application/pdf",
    "visible_to_patient": true,
    "created_at": "2026-10-20 12:03:50 -0400",
    "updated_at": "2026-10-20 12:20:12 -0400",
    "extra_fields": {
      "extension": "pdf",
      "owner": { "organization": { "id": "102938" } },
      "changed_fields": ["display_name"],
      "resourceIdType": "Document"
    }
  }
}
```

Deliveries are not ordered: keep the newest state per `resource_id`. Order the events by the
envelope's `occurredAt`, not by `updated_at`: `updated_at` does not move on a visibility change, so
two events can share it and differ in `visible_to_patient`, and its local offset does not sort as a
string. `occurredAt` has one-second precision, so two events in the same second can still tie.

> [!NOTE]
>
> Treat every `patient_document.*` event as PHI: `patient_ref` ties the document to a patient, and
> `title` can name a condition or a test.

### Appointments

`appointment.created` fires when an appointment is created, `appointment.updated` when it changes
(reschedule, status change), and `appointment.deleted` when it is cancelled / deleted; each delivers
the canonical appointment snapshot.

Appointments come from **two producers** — subscribe to the versions you need:

* **Clinical appointments (`1.0`)** — appointments created by OpenLoop's care workflow, emitted at
  `1.0`. `extra_fields` is the source record's native object (opaque). It emits
  `appointment.created` and `appointment.updated` only: a cancelled or deleted clinical appointment
  sends no `appointment.deleted`, so read the cancellation from `status` on `appointment.updated`.
* **Scheduling appointments (`1.1` / `1.2` / `2.0`)** — appointments booked through OpenLoop's scheduling
  service (your own `/v0.1/appointments` bookings). It is first-party, so `extra_fields` is the
  defined `SchedulingAppointmentExtra` object (table in the `2.0` tab), not a passthrough.
  `1.1` omits `appointment_type_refs`; `1.2` and `2.0` add it as a required field. The scheduling
  producer emits `2.0`, falling back to `1.1` where `appointment_type_refs` is unavailable.

`appointment.created`, `appointment.updated` and `appointment.deleted` carry the same canonical data
shape. The versions differ in `extra_fields`; `1.0` can also carry `emr_patient_id`, and `2.0` adds
`provider_name` and `video_meeting_url`.

> [tab] 1.0 (default)
>
> | Field | Type | Required | Nullable | Description |
> | - | - | - | - | - |
> | `resource_id` | string | Yes | No | Canonical appointment id (surrogate key). |
> | `resource_organization_id` | string | Yes | Yes | Opaque reference to the organization that holds the record. It is not your OpenLoop organization id. `null` when unknown. |
> | `status` | string | Yes | No | Canonical status, one of `scheduled`, `confirmed`, `cancelled`, `completed`, `no_show`, `unknown`. |
> | `start` | string | Yes | Yes | Start timestamp (ISO-8601). |
> | `end` | string | Yes | Yes | End timestamp. |
> | `duration_minutes` | number | Yes | Yes | Duration in minutes. |
> | `appointment_type` | string | Yes | Yes | Canonical appointment type label. |
> | `patient_ref` | string | Yes | Yes | Patient reference (surrogate). |
> | `provider_ref` | string | Yes | Yes | Provider reference (surrogate). |
> | `location` | string | Yes | Yes | Location. |
> | `created_at` | string | Yes | Yes | Creation timestamp. |
> | `updated_at` | string | Yes | Yes | Last-update timestamp. |
> | `emr_patient_id` | string | No | No | The patient's id, the `id` that `GET /v0.1/patients/{id}` takes, when known; omitted otherwise. |
> | `extra_fields` | object | Yes | No | Passthrough; not part of the versioned contract (see note below). |

> [tab] 1.1
>
> | Field | Type | Required | Nullable | Description |
> | - | - | - | - | - |
> | `resource_id` | string | Yes | No | Canonical appointment id (surrogate key). |
> | `resource_organization_id` | string | Yes | Yes | Owning organization id; `null` when unknown. |
> | `status` | string | Yes | No | Canonical status, one of `scheduled`, `confirmed`, `cancelled`, `completed`, `no_show`, `unknown`. |
> | `start` | string | Yes | Yes | Start timestamp (ISO-8601). |
> | `end` | string | Yes | Yes | End timestamp. |
> | `duration_minutes` | number | Yes | Yes | Duration in minutes. |
> | `appointment_type` | string | Yes | Yes | Canonical appointment type label. |
> | `patient_ref` | string | Yes | Yes | Patient reference (surrogate). |
> | `provider_ref` | string | Yes | Yes | Provider reference (surrogate). |
> | `location` | string | Yes | Yes | Location. |
> | `created_at` | string | Yes | Yes | Creation timestamp. |
> | `updated_at` | string | Yes | Yes | Last-update timestamp. |
> | `extra_fields` | object | Yes | No | Scheduling change envelope (`SchedulingAppointmentExtra`); sub-fields below. |
> | `extra_fields.change` | string | Yes | No | What happened, one of `booked`, `rescheduled`, `cancelled`, `completed`, `no_show`, `reopened`, `unresolved`, `deleted`. |
> | `extra_fields.changed_fields` | array | Yes | No | Canonical field names that changed, from `status`, `start`, `end`, `provider_ref`, `deleted_at`. |
> | `extra_fields.previous` | object | Yes | No | Prior values of the changed canonical fields; only changed keys present. |
> | `extra_fields.appointment_type_id` | string | Yes | Yes | Scheduling appointment-type id. |
> | `extra_fields.cancel_reason` | string | Yes | Yes | Cancellation reason; set on `appointment.deleted`, else `null`. |
> | `extra_fields.deleted_at` | string | Yes | Yes | Deletion timestamp; set on `appointment.deleted`, else `null`. |
> | `extra_fields.external_refs` | array | Yes | No | External system references, each `{ system, id }`. |
> | `extra_fields.test` | boolean | Yes | No | Whether the booking is a test record. |
> | `extra_fields.version` | number | Yes | No | Scheduling-service internal revision counter. |

> [tab] 1.2
>
> | Field | Type | Required | Nullable | Description |
> | - | - | - | - | - |
> | `resource_id` | string | Yes | No | Canonical appointment id (surrogate key). |
> | `resource_organization_id` | string | Yes | Yes | Owning organization id; `null` when unknown. |
> | `status` | string | Yes | No | Canonical status, one of `scheduled`, `confirmed`, `cancelled`, `completed`, `no_show`, `unknown`. |
> | `start` | string | Yes | Yes | Start timestamp (ISO-8601). |
> | `end` | string | Yes | Yes | End timestamp. |
> | `duration_minutes` | number | Yes | Yes | Duration in minutes. |
> | `appointment_type` | string | Yes | Yes | Canonical appointment type label. |
> | `patient_ref` | string | Yes | Yes | Patient reference (surrogate). |
> | `provider_ref` | string | Yes | Yes | Provider reference (surrogate). |
> | `location` | string | Yes | Yes | Location. |
> | `created_at` | string | Yes | Yes | Creation timestamp. |
> | `updated_at` | string | Yes | Yes | Last-update timestamp. |
> | `extra_fields` | object | Yes | No | Scheduling change envelope (`SchedulingAppointmentExtra` with the `1.2`/`2.0` `appointment_type_refs`); sub-fields below. |
> | `extra_fields.change` | string | Yes | No | What happened, one of `booked`, `rescheduled`, `cancelled`, `completed`, `no_show`, `reopened`, `unresolved`, `deleted`. |
> | `extra_fields.changed_fields` | array | Yes | No | Canonical field names that changed, from `status`, `start`, `end`, `provider_ref`, `deleted_at`. |
> | `extra_fields.previous` | object | Yes | No | Prior values of the changed canonical fields; only changed keys present. |
> | `extra_fields.appointment_type_id` | string | Yes | Yes | Scheduling appointment-type id. |
> | `extra_fields.appointment_type_refs` | array | Yes | No | External appointment-type references, each `{ system, id }`. |
> | `extra_fields.cancel_reason` | string | Yes | Yes | Cancellation reason; set on `appointment.deleted`, else `null`. |
> | `extra_fields.deleted_at` | string | Yes | Yes | Deletion timestamp; set on `appointment.deleted`, else `null`. |
> | `extra_fields.external_refs` | array | Yes | No | External system references, each `{ system, id }`. |
> | `extra_fields.test` | boolean | Yes | No | Whether the booking is a test record. |
> | `extra_fields.version` | number | Yes | No | Scheduling-service internal revision counter. |

> [tab] 2.0
>
> | Field | Type | Required | Nullable | Description |
> | - | - | - | - | - |
> | `resource_id` | string | Yes | No | Canonical appointment id (surrogate key). |
> | `resource_organization_id` | string | Yes | Yes | Owning organization id; `null` when unknown. |
> | `status` | string | Yes | No | Canonical status, one of `scheduled`, `confirmed`, `cancelled`, `completed`, `no_show`, `unknown`. |
> | `start` | string | Yes | Yes | Start timestamp (ISO-8601). |
> | `end` | string | Yes | Yes | End timestamp. |
> | `duration_minutes` | number | Yes | Yes | Duration in minutes. |
> | `appointment_type` | string | Yes | Yes | Canonical appointment type label. |
> | `patient_ref` | string | Yes | Yes | Patient reference (surrogate). |
> | `provider_ref` | string | Yes | Yes | Provider reference (surrogate). |
> | `provider_name` | string | Yes | Yes | The clinician's display name, so you can show it without resolving `provider_ref`; `null` when the clinician has no name on record. |
> | `location` | string | Yes | Yes | Location. |
> | `video_meeting_url` | string | Yes | Yes | The link the patient joins the video visit with; `null` when the appointment has none. |
> | `created_at` | string | Yes | Yes | Creation timestamp. |
> | `updated_at` | string | Yes | Yes | Last-update timestamp. |
> | `extra_fields` | object | Yes | No | Scheduling change envelope (`SchedulingAppointmentExtra` with the `1.2`/`2.0` `appointment_type_refs`); sub-fields below. |
> | `extra_fields.change` | string | Yes | No | What happened, one of `booked`, `rescheduled`, `cancelled`, `completed`, `no_show`, `reopened`, `unresolved`, `deleted`. |
> | `extra_fields.changed_fields` | array | Yes | No | Canonical field names that changed, from `status`, `start`, `end`, `provider_ref`, `deleted_at`. |
> | `extra_fields.previous` | object | Yes | No | Prior values of the changed canonical fields; only changed keys present. |
> | `extra_fields.appointment_type_id` | string | Yes | Yes | Scheduling appointment-type id. |
> | `extra_fields.appointment_type_refs` | array | Yes | No | External appointment-type references, each `{ system, id }`. |
> | `extra_fields.cancel_reason` | string | Yes | Yes | Cancellation reason; set on `appointment.deleted`, else `null`. |
> | `extra_fields.deleted_at` | string | Yes | Yes | Deletion timestamp; set on `appointment.deleted`, else `null`. |
> | `extra_fields.external_refs` | array | Yes | No | External system references, each `{ system, id }`. |
> | `extra_fields.test` | boolean | Yes | No | Whether the booking is a test record. |
> | `extra_fields.version` | number | Yes | No | Scheduling-service internal revision counter. |

The canonical fields are the same across versions, except that `1.0` can carry `emr_patient_id`
and `2.0` adds `provider_name` and `video_meeting_url`; otherwise the producers differ only in
`extra_fields`. At `1.0`, `extra_fields` is the source record's native object, not covered by
`eventVersion` — treat it as opaque. At `1.1` / `1.2` / `2.0`
`extra_fields` is the structured `SchedulingAppointmentExtra` above — `1.1` without
`appointment_type_refs`, `1.2` and `2.0` with it.

#### Matching an event's status to an appointment read

`GET /v0.1/appointments` and the scheduling events (`1.1` / `1.2` / `2.0`) describe the same state in
different words. The read has a `status` of `open` or `closed`, with an `outcome` once it closes.
The event has one canonical `data.status`:

| Read `status` | Read `outcome` | Event `data.status` |
| - | - | - |
| `open` | (none) | `scheduled` |
| `closed` | `completed` | `completed` |
| `closed` | `no_show` | `no_show` |
| `closed` | `cancelled` | `cancelled` |
| `closed` | `unresolved` | `unknown` |

Two cases where the read and the latest event differ:

* **Deleted appointments.** `appointment.deleted` carries the status the appointment had when it
  was deleted, often `scheduled`. Treat the event type, or `extra_fields.deleted_at`, as the
  deletion, not `status`. A deleted appointment no longer appears in `GET /v0.1/appointments`.
* **Unresolved appointments.** When a reopened appointment finds no clinician for its window, it
  stays closed with outcome `unresolved`, and no event is sent for that change. The read is the only
  place it shows.

Clinical appointments at `1.0`:

```json appointment.created theme={null}
{
  "id": "e4a19f6c02...3b8",
  "type": "appointment.created",
  "eventVersion": "1.0",
  "occurredAt": "2026-10-20T17:30:21.000Z",
  "data": {
    "resource_id": "a81c3e5f-2b4d-4f6a-8c0e-1d3f5a7b9c2e",
    "resource_organization_id": "8f3c2a1d-6b4e-4d7a-9c5f-0e2b4d6f8a1c",
    "status": "scheduled",
    "start": "2026-10-23T15:00:00.000Z",
    "end": "2026-10-23T15:30:00.000Z",
    "duration_minutes": 30,
    "appointment_type": "Initial consultation",
    "patient_ref": "3f2b9c1e-7a4d-4e8b-9c21-5d6e7f8a9b0c",
    "provider_ref": "6c4e2a0b-9d7f-4b5c-a3e1-f0d2c4b6a8e1",
    "location": null,
    "created_at": "2026-10-20T17:30:19.000Z",
    "updated_at": "2026-10-20T17:30:19.482Z",
    "extra_fields": { "…": "source record passthrough; not part of the contract" }
  }
}
```

```json appointment.updated theme={null}
{
  "id": "7d52b0e8f1...9ac",
  "type": "appointment.updated",
  "eventVersion": "1.0",
  "occurredAt": "2026-10-21T13:05:47.000Z",
  "data": {
    "resource_id": "a81c3e5f-2b4d-4f6a-8c0e-1d3f5a7b9c2e",
    "resource_organization_id": "8f3c2a1d-6b4e-4d7a-9c5f-0e2b4d6f8a1c",
    "status": "scheduled",
    "start": "2026-10-24T16:00:00.000Z",
    "end": "2026-10-24T16:30:00.000Z",
    "duration_minutes": 30,
    "appointment_type": "Initial consultation",
    "patient_ref": "3f2b9c1e-7a4d-4e8b-9c21-5d6e7f8a9b0c",
    "provider_ref": "6c4e2a0b-9d7f-4b5c-a3e1-f0d2c4b6a8e1",
    "location": null,
    "created_at": "2026-10-20T17:30:19.000Z",
    "updated_at": "2026-10-21T13:05:45.910Z",
    "extra_fields": { "…": "source record passthrough; not part of the contract" }
  }
}
```

At `1.0`, `appointment.updated` carries the full snapshot after the change and no list of what
changed. Compare it to the appointment you hold.

### Intake

`intake.created` fires when a patient's intake (questionnaire response) is created, `intake.signed`
when it is signed, and `intake.completed` when it is completed (finished / locked). `intake.completed`
sets canonical `status` to `completed`; `intake.signed` populates
`extra_fields.formAnswerGroup.form_answer_group_signings` at `1.0`.

`intake.created`, `intake.signed` and `intake.completed` carry the same data shape.

> [tab] 1.0 (default)
>
> | Field | Type | Required | Nullable | Description |
> | - | - | - | - | - |
> | `resource_id` | string | Yes | No | Intake resource id. |
> | `resource_organization_id` | string | Yes | Yes | Opaque reference to the organization that holds the record. It is not your OpenLoop organization id. |
> | `status` | string | Yes | No | Canonical intake status, one of `in_progress`, `completed`, `amended`, `stopped`, `unknown`. |
> | `patient_ref` | string | Yes | Yes | Patient reference (surrogate). |
> | `emr_patient_id` | string | No | No | The patient's id, the `id` that `GET /v0.1/patients/{id}` takes, when known; omitted otherwise. |
> | `questionnaire_ref` | string | Yes | Yes | Questionnaire / form id. |
> | `encounter_id` | string | No | Yes | Partner API encounter the intake belongs to: the same `encounter_id` your completed submit returned. `null` when the form is not linked to one, or when the producer has not been upgraded yet. On staging today; absent (not `null`) on events delivered before the field existed. |
> | `program` | string | Yes | Yes | Intake program resolved by the producer. |
> | `intake_kind` | string | Yes | Yes | One of `initial`, `refill`, `multi_month`, `labs`, `unknown`; `null` when unclassified. |
> | `organization` | object | Yes | No | OpenLoop-native org identity. |
> | `organization.id` | string | Yes | Yes | OpenLoop org id. |
> | `organization.name` | string | Yes | Yes | OpenLoop org name. |
> | `authored_at` | string | Yes | Yes | When the form was locked. As the source reports it, e.g. `2026-10-20 12:03:50 -0400`: a local offset, not ISO-8601 UTC. |
> | `created_at` | string | Yes | Yes | Creation timestamp. As the source reports it, e.g. `2026-10-20 12:03:50 -0400`: a local offset, not ISO-8601 UTC. |
> | `updated_at` | string | Yes | Yes | Last-update timestamp. As the source reports it, e.g. `2026-10-20 12:03:50 -0400`: a local offset, not ISO-8601 UTC. |
> | `extra_fields` | object | Yes | No | Passthrough (see note below). |

> [tab] 1.1
>
> | Field | Type | Required | Nullable | Description |
> | - | - | - | - | - |
> | `resource_id` | string | Yes | No | Intake resource id. |
> | `resource_organization_id` | string | Yes | Yes | Opaque reference to the organization that holds the record. It is not your OpenLoop organization id. |
> | `status` | string | Yes | No | Canonical intake status, one of `in_progress`, `completed`, `amended`, `stopped`, `unknown`. |
> | `patient_ref` | string | Yes | Yes | Patient reference (surrogate). |
> | `emr_patient_id` | string | No | No | The patient's id, the `id` that `GET /v0.1/patients/{id}` takes, when known; omitted otherwise. |
> | `questionnaire_ref` | string | Yes | Yes | Questionnaire / form id. |
> | `encounter_id` | string | No | Yes | Partner API encounter the intake belongs to: the same `encounter_id` your completed submit returned. `null` when the form is not linked to one, or when the producer has not been upgraded yet. On staging today; absent (not `null`) on events delivered before the field existed. |
> | `program` | string | Yes | Yes | An internal OpenLoop id for the space the intake was submitted in, not a program code. Do not branch on it. |
> | `intake_kind` | string | Yes | Yes | One of `initial`, `refill`, `multi_month`, `labs`, `unknown`; `null` when unclassified. Always `null` on `1.1` today. |
> | `organization` | object | Yes | No | OpenLoop-native org identity. |
> | `organization.id` | string | Yes | Yes | OpenLoop org id. Always `null` on `1.1` today. |
> | `organization.name` | string | Yes | Yes | OpenLoop org name. Always `null` on `1.1` today. |
> | `authored_at` | string | Yes | Yes | Authored timestamp (ISO-8601). |
> | `created_at` | string | Yes | Yes | Creation timestamp. Always `null` on `1.1` today. |
> | `updated_at` | string | Yes | Yes | Last-update timestamp. |
> | `concept_ids` | object | Yes | Yes | Map of concept → ids (`Record<string, number[]>`); `null` when nothing resolved. |
> | `eligibility` | object | Yes | Yes | **Always `null` today.** The eligibility result is now recorded as the fired-rule list that only `2.0` carries, and `2.0` is not emitted yet. The `1.1` object shape (`overall`, `next_step`, `reasons[]`, `derived`, `program`, `ruleset_version`) is not sent. |
> | `extra_fields` | object | Yes | No | Passthrough (see note below). |

> [tab] 2.0
>
> | Field | Type | Required | Nullable | Description |
> | - | - | - | - | - |
> | `resource_id` | string | Yes | No | Intake resource id. |
> | `resource_organization_id` | string | Yes | Yes | Opaque reference to the organization that holds the record. It is not your OpenLoop organization id. |
> | `status` | string | Yes | No | Canonical intake status, one of `in_progress`, `completed`, `amended`, `stopped`, `unknown`. |
> | `patient_ref` | string | Yes | Yes | Patient reference (surrogate). |
> | `emr_patient_id` | string | No | No | The patient's id, the `id` that `GET /v0.1/patients/{id}` takes, when known; omitted otherwise. |
> | `questionnaire_ref` | string | Yes | Yes | Questionnaire / form id. |
> | `encounter_id` | string | No | Yes | Partner API encounter the intake belongs to: the same `encounter_id` your completed submit returned. `null` when the form is not linked to one, or when the producer has not been upgraded yet. On staging today; absent (not `null`) on events delivered before the field existed. |
> | `program` | string | Yes | Yes | Intake program resolved by the producer. |
> | `intake_kind` | string | Yes | Yes | One of `initial`, `refill`, `multi_month`, `labs`, `unknown`; `null` when unclassified. |
> | `organization` | object | Yes | No | OpenLoop-native org identity. |
> | `organization.id` | string | Yes | Yes | OpenLoop org id. |
> | `organization.name` | string | Yes | Yes | OpenLoop org name. |
> | `authored_at` | string | Yes | Yes | Authored timestamp (ISO-8601). |
> | `created_at` | string | Yes | Yes | Creation timestamp. |
> | `updated_at` | string | Yes | Yes | Last-update timestamp. |
> | `concept_ids` | object | Yes | Yes | Numeric coded concepts per link\_id (`Record<string, number[]>`); `null` when nothing resolved. |
> | `eligibility` | array | Yes | Yes | Fired rule events in ordinal order (`IntakeEligibilityEvent[]`), each `{ type, params }`. `[]` = evaluated, nothing fired; `null` = not evaluated or unreadable. |
> | `extra_fields` | object | Yes | No | Passthrough (see note below). |

`1.0` and `1.1` are not two shapes of the same intake: they come from different places.

* **`1.1`** is emitted for intakes submitted through this API. If you submit intakes yourself, this
  is the version that carries them.
* **`1.0`** is emitted for intakes completed in OpenLoop's own care workflow. `intake.signed` exists
  only here.

`2.0` is subscribable but not emitted today.

> [!WARNING]
>
> A subscription without a version, or to `intake.*`, resolves to the `1.0` default. It never receives
> the `1.1` events for intakes you submitted through this API. Ask your OpenLoop contact to subscribe
> your endpoint to `intake.created` and `intake.completed` at `1.1`.

```json intake.created theme={null}
{
  "id": "2a7e91c4f0...d15",
  "type": "intake.created",
  "eventVersion": "1.0",
  "occurredAt": "2026-10-20T15:44:03.000Z",
  "data": {
    "resource_id": "2281904",
    "resource_organization_id": "102938",
    "status": "in_progress",
    "patient_ref": "6650172",
    "questionnaire_ref": "1975412",
    "encounter_id": "e7c1a9f2-3b5d-4c8e-9a0f-2d4b6c8e0a1f",
    "program": "MWL_MCO",
    "intake_kind": "initial",
    "organization": { "id": "01M56WBWCFPSS2W3GRHZMVTPSB", "name": "Acme Health" },
    "authored_at": null,
    "created_at": "2026-10-20 11:44:02 -0400",
    "updated_at": "2026-10-20 11:44:02 -0400",
    "extra_fields": {
      "changed_fields": [],
      "formAnswerGroup": {
        "name": "Weight management intake",
        "finished": false,
        "is_locked": false,
        "form_answer_group_signings": [],
        "…": "other source fields; passthrough, not part of the contract"
      }
    }
  }
}
```

```json intake.signed theme={null}
{
  "id": "b40c6d2e8a...71f",
  "type": "intake.signed",
  "eventVersion": "1.0",
  "occurredAt": "2026-10-20T15:52:30.000Z",
  "data": {
    "resource_id": "2281904",
    "resource_organization_id": "102938",
    "status": "in_progress",
    "patient_ref": "6650172",
    "questionnaire_ref": "1975412",
    "encounter_id": "e7c1a9f2-3b5d-4c8e-9a0f-2d4b6c8e0a1f",
    "program": "MWL_MCO",
    "intake_kind": "initial",
    "organization": { "id": "01M56WBWCFPSS2W3GRHZMVTPSB", "name": "Acme Health" },
    "authored_at": null,
    "created_at": "2026-10-20 11:44:02 -0400",
    "updated_at": "2026-10-20 11:52:29 -0400",
    "extra_fields": {
      "changed_fields": [],
      "formAnswerGroup": {
        "name": "Weight management intake",
        "finished": false,
        "is_locked": false,
        "form_answer_group_signings": [{ "id": "88120", "created_at": "2026-10-20 11:52:29 -0400", "user": { "id": "6650172" } }],
        "…": "other source fields; passthrough, not part of the contract"
      }
    }
  }
}
```

```json intake.completed theme={null}
{
  "id": "f93a1b7d5c...2e0",
  "type": "intake.completed",
  "eventVersion": "1.0",
  "occurredAt": "2026-10-20T15:52:41.000Z",
  "data": {
    "resource_id": "2281904",
    "resource_organization_id": "102938",
    "status": "completed",
    "patient_ref": "6650172",
    "questionnaire_ref": "1975412",
    "encounter_id": "e7c1a9f2-3b5d-4c8e-9a0f-2d4b6c8e0a1f",
    "program": "MWL_MCO",
    "intake_kind": "initial",
    "organization": { "id": "01M56WBWCFPSS2W3GRHZMVTPSB", "name": "Acme Health" },
    "authored_at": "2026-10-20 11:52:40 -0400",
    "created_at": "2026-10-20 11:44:02 -0400",
    "updated_at": "2026-10-20 11:52:40 -0400",
    "extra_fields": {
      "changed_fields": ["is_locked"],
      "formAnswerGroup": {
        "name": "Weight management intake",
        "finished": true,
        "is_locked": true,
        "form_answer_group_signings": [{ "id": "88120", "created_at": "2026-10-20 11:52:29 -0400", "user": { "id": "6650172" } }],
        "…": "other source fields; passthrough, not part of the contract"
      }
    }
  }
}
```

```json intake.completed (1.1) theme={null}
{
  "id": "0d6e4b2a9f...c83",
  "type": "intake.completed",
  "eventVersion": "1.1",
  "occurredAt": "2026-10-20T18:10:05.000Z",
  "data": {
    "resource_id": "9b1d3f5a-7c9e-4b2d-8f0a-1c3e5a7b9d2f",
    "resource_organization_id": "8f3c2a1d-6b4e-4d7a-9c5f-0e2b4d6f8a1c",
    "status": "completed",
    "patient_ref": "3f2b9c1e-7a4d-4e8b-9c21-5d6e7f8a9b0c",
    "questionnaire_ref": "Questionnaire/mwl-intake",
    "encounter_id": "e7c1a9f2-3b5d-4c8e-9a0f-2d4b6c8e0a1f",
    "program": "c1e4a7b2-5d8f-4a3c-9e6b-2f0d4c8a1e57",
    "intake_kind": null,
    "organization": { "id": null, "name": null },
    "authored_at": "2026-10-20T18:10:01.000Z",
    "created_at": null,
    "updated_at": "2026-10-20T18:10:03.274Z",
    "concept_ids": { "current_medications": [314231, 860975] },
    "eligibility": null,
    "extra_fields": { "…": "source record passthrough, including the answers (PHI); not part of the contract" }
  }
}
```

`intake.signed` and `intake.completed` for the same form share `resource_id`, and a signed form is
not always `completed`. Tell them apart by `type`, not by `status`: deduping on `resource_id` alone
drops one of them.

`extra_fields` is the source record's native payload; its shape varies and is not covered by
`eventVersion`.

> [!NOTE]
>
> Intake payloads carry PHI, so handle them with the same care as patient data. At `1.1` that includes
> the answer tree in `extra_fields`; `1.0` carries no answers, but its patient references are still
> PHI.

### Charting

`charting.created`, `charting.signed` and `charting.completed` fire for a clinician's **charting
form** — any clinical form that is not one of the intake forms — when it is created, signed, and
completed (finished / locked). They share the intake shape minus `program`, `intake_kind`,
`concept_ids` and `eligibility`. Today they carry **metadata only**: no answers, no note body.

The three types carry the same data shape. Only `1.0` exists, so a default subscription and a
wildcard both receive what is emitted. Selections are expanded when the endpoint is saved: an
endpoint registered with `*` before these types existed does not receive them until its
subscriptions are updated, and `intake.*` never covers them; add `charting.*` or the three types.

> [tab] 1.0 (default)
>
> | Field | Type | Required | Nullable | Description |
> | - | - | - | - | - |
> | `resource_id` | string | Yes | No | Id of the charting form instance. |
> | `resource_organization_id` | string | Yes | Yes | Opaque reference to the organization that holds the record. It is not your OpenLoop organization id. |
> | `status` | string | Yes | No | Canonical status, one of `in_progress`, `completed`, `amended`, `stopped`, `unknown`. `charting.completed` sets `completed`. |
> | `patient_ref` | string | Yes | Yes | Patient reference. It is not guaranteed to be a `/v0.1` patient id; see [Correlating events to your records](#correlating-events-to-your-records). |
> | `emr_patient_id` | string | No | No | The patient's id, the `id` that `GET /v0.1/patients/{id}` takes, when known; omitted otherwise. |
> | `questionnaire_ref` | string | Yes | Yes | Form id. On the partner surface it is the tail of `questionnaire_canonical`, which ends in `/<questionnaire_ref>`; the prefix is the form's URL and is not a contract, so match the tail only. |
> | `encounter_id` | string | No | Yes | Partner API encounter the note belongs to, the same id your intake submit returned; `null` when the form was started outside the charting workflow and is not linked to one, or when the producer has not been upgraded yet. On staging today; absent (not `null`) on events delivered before the field existed. |
> | `organization` | object | Yes | No | OpenLoop-native org identity. |
> | `organization.id` | string | Yes | Yes | OpenLoop org id. |
> | `organization.name` | string | Yes | Yes | OpenLoop org name. |
> | `authored_at` | string | Yes | Yes | When the form was locked; `null` until then. As the source reports it, e.g. `2026-10-20 12:03:50 -0400`: a local offset, not ISO-8601 UTC. |
> | `created_at` | string | Yes | Yes | When the form was saved; for a form linked to an appointment, the appointment's date and time of service instead. `extra_fields.formAnswerGroup.record_created_at` is when the record was created. As the source reports it, e.g. `2026-10-20 12:03:50 -0400`: a local offset, not ISO-8601 UTC. |
> | `updated_at` | string | Yes | Yes | Last-update timestamp. As the source reports it, e.g. `2026-10-20 12:03:50 -0400`: a local offset, not ISO-8601 UTC. |
> | `extra_fields` | object | Yes | No | Passthrough, metadata only (see note below). |
> | `extra_fields.changed_fields` | array | Yes | No | Field names that changed at the source. |
> | `extra_fields.formAnswerGroup` | object | Yes | Yes | `name`, `finished`, `is_locked`, `frozen`, `deleted_at`, `record_created_at`, `external_id`, `user { id }`, `filler { id }`, `locked_by { id }`, `appointment { id }`, `form_answer_group_signings[] { id, created_at, user { id } }`. No answers. |

```json charting.created theme={null}
{
  "id": "6b8d0f2a4c...e57",
  "type": "charting.created",
  "eventVersion": "1.0",
  "occurredAt": "2026-10-20T16:30:13.000Z",
  "data": {
    "resource_id": "2290417",
    "resource_organization_id": "102938",
    "status": "in_progress",
    "patient_ref": "6650172",
    "questionnaire_ref": "2104388",
    "encounter_id": "e7c1a9f2-3b5d-4c8e-9a0f-2d4b6c8e0a1f",
    "organization": { "id": "01M56WBWCFPSS2W3GRHZMVTPSB", "name": "Acme Health" },
    "authored_at": null,
    "created_at": "2026-10-20 12:30:00 -0400",
    "updated_at": "2026-10-20 12:30:12 -0400",
    "extra_fields": {
      "changed_fields": [],
      "formAnswerGroup": {
        "name": "Provider visit note",
        "finished": false,
        "is_locked": false,
        "frozen": false,
        "deleted_at": null,
        "record_created_at": "2026-10-20 12:30:12 -0400",
        "external_id": null,
        "user": { "id": "6650172" },
        "filler": { "id": "5512093" },
        "locked_by": null,
        "appointment": { "id": "40718822" },
        "form_answer_group_signings": []
      }
    }
  }
}
```

```json charting.signed theme={null}
{
  "id": "d1f3a5c7e9...b24",
  "type": "charting.signed",
  "eventVersion": "1.0",
  "occurredAt": "2026-10-20T16:58:41.000Z",
  "data": {
    "resource_id": "2290417",
    "resource_organization_id": "102938",
    "status": "in_progress",
    "patient_ref": "6650172",
    "questionnaire_ref": "2104388",
    "encounter_id": "e7c1a9f2-3b5d-4c8e-9a0f-2d4b6c8e0a1f",
    "organization": { "id": "01M56WBWCFPSS2W3GRHZMVTPSB", "name": "Acme Health" },
    "authored_at": null,
    "created_at": "2026-10-20 12:30:00 -0400",
    "updated_at": "2026-10-20 12:58:40 -0400",
    "extra_fields": {
      "changed_fields": [],
      "formAnswerGroup": {
        "name": "Provider visit note",
        "finished": false,
        "is_locked": false,
        "frozen": false,
        "deleted_at": null,
        "record_created_at": "2026-10-20 12:30:12 -0400",
        "external_id": null,
        "user": { "id": "6650172" },
        "filler": { "id": "5512093" },
        "locked_by": null,
        "appointment": { "id": "40718822" },
        "form_answer_group_signings": [{ "id": "88231", "created_at": "2026-10-20 12:58:40 -0400", "user": { "id": "5512093" } }]
      }
    }
  }
}
```

```json charting.completed theme={null}
{
  "id": "3e5a7c9b1d...f60",
  "type": "charting.completed",
  "eventVersion": "1.0",
  "occurredAt": "2026-10-20T16:59:02.000Z",
  "data": {
    "resource_id": "2290417",
    "resource_organization_id": "102938",
    "status": "completed",
    "patient_ref": "6650172",
    "questionnaire_ref": "2104388",
    "encounter_id": "e7c1a9f2-3b5d-4c8e-9a0f-2d4b6c8e0a1f",
    "organization": { "id": "01M56WBWCFPSS2W3GRHZMVTPSB", "name": "Acme Health" },
    "authored_at": "2026-10-20 12:59:01 -0400",
    "created_at": "2026-10-20 12:30:00 -0400",
    "updated_at": "2026-10-20 12:59:01 -0400",
    "extra_fields": {
      "changed_fields": ["is_locked"],
      "formAnswerGroup": {
        "name": "Provider visit note",
        "finished": true,
        "is_locked": true,
        "frozen": false,
        "deleted_at": null,
        "record_created_at": "2026-10-20 12:30:12 -0400",
        "external_id": null,
        "user": { "id": "6650172" },
        "filler": { "id": "5512093" },
        "locked_by": { "id": "5512093" },
        "appointment": { "id": "40718822" },
        "form_answer_group_signings": [{ "id": "88231", "created_at": "2026-10-20 12:58:40 -0400", "user": { "id": "5512093" } }]
      }
    }
  }
}
```

There are no answers and no note body in any of them; read the note as described below.

Charting is **delivered on staging only today**; production emission is
switched off until OpenLoop enables it, and your subscription is added by your implementation contact.

> [!NOTE]
>
> **Key on `data.encounter_id`.** A note that OpenLoop's charting workflow writes is stamped with the
> encounter your completed intake created, and the event carries that id as `data.encounter_id`. It is
> the same `encounter_id` your intake submit returned, so you can match the event to your own record
> before you read anything. The note itself reaches the partner surface as a questionnaire response on
> that encounter (the encounter filter was verified on staging 2026-10-19).

**From a charting event to the note.** On `charting.completed` only, list the completed responses
on the event's encounter. `charting.created` and `charting.signed` arrive while the form is still
`in_progress` (a signed form is not yet locked), so the read below returns nothing for them.

```
GET /v0.1/questionnaire-responses?encounter_id=<data.encounter_id>&status=completed
```

The list holds every completed response on that encounter — your intake and the note. The note is
the row whose `questionnaire_canonical` ends in `/<questionnaire_ref>` (the event's
`questionnaire_ref`; match the tail, the prefix is the form's URL and is not a contract); if
several match, take the newest `updated_at`. Its `answers` carry the note text. Such rows omit
`questionnaire_id`, so do not filter by one. Match on canonical and encounter, not on list position.
The event and the row are written by different steps, so if the row is not listed yet, retry with
backoff; do not compare `updated_at` to `occurredAt`.

The cookbook page [Encounter notes](https://openloop.mintlify.site/cookbook/encounter-notes.md) walks through the subscription,
the event and the read with samples.

When `data.encounter_id` is `null`, the form was started outside the charting workflow and is
written against the patient only, so find it through the patient: `data.emr_patient_id`, when the
event carries it, is the `/v0.1` patient id, and
`GET /v0.1/questionnaire-responses?subject=Patient/<data.emr_patient_id>&status=completed` lists the
form. The key is omitted when the id isn't known, never `null`; without it, `patient_ref` is not
guaranteed to be a `/v0.1` patient id, so how your tenant maps it to a patient is agreed with your
implementation contact when the endpoint is registered. See
[Correlating events to your records](#correlating-events-to-your-records).

### Intake appointments

`intake_appointment.created` fires when an intake form is first linked to an appointment and
`intake_appointment.updated` when that link changes.

`intake_appointment.created` and `intake_appointment.updated` carry the same data shape.

> [tab] 1.0 (default)
>
> | Field | Type | Required | Nullable | Description |
> | - | - | - | - | - |
> | `resource_id` | string | Yes | No | Id for the intake-appointment link. |
> | `resource_organization_id` | string | Yes | Yes | Opaque reference to the organization that holds the record. It is not your OpenLoop organization id. |
> | `appointment_id` | string | Yes | Yes | Linked appointment id. |
> | `form_answer_group_id` | string | Yes | Yes | Linked intake form answer group id. (Renamed to `intake_id` at `2.0`.) |
> | `extra_fields` | object | Yes | No | Carries `changed_fields` only. |

> [tab] 2.0
>
> | Field | Type | Required | Nullable | Description |
> | - | - | - | - | - |
> | `resource_id` | string | Yes | No | Id for the intake-appointment link. |
> | `resource_organization_id` | string | Yes | Yes | Opaque reference to the organization that holds the record. It is not your OpenLoop organization id. |
> | `appointment_id` | string | Yes | Yes | Linked appointment id. |
> | `intake_id` | string | Yes | Yes | Linked intake form answer group id. (Named `form_answer_group_id` at `1.0`.) |
> | `start` | string | Yes | Yes | Appointment start timestamp (ISO-8601). |
> | `end` | string | Yes | Yes | Appointment end timestamp. |
> | `duration_minutes` | number | Yes | Yes | Duration in minutes. |
> | `appointment_type` | string | Yes | Yes | Appointment type label. |
> | `location` | string | Yes | Yes | Location. |
> | `extra_fields` | object | Yes | No | Carries `changed_fields` only. |

> [!WARNING]
>
> The producer emits only 2.0 today — subscribing to the 1.0 default receives nothing.

`extra_fields` here is not a passthrough; it carries only `changed_fields` (the names of fields
that changed).

### Requested form completions

`requested_form_completion.created` fires when a patient is sent a request to fill out a form,
`requested_form_completion.updated` when the request's `status` changes, and
`requested_form_completion.deleted` when the request is deleted. These events report the
**request**, not the submitted form: the submitted form is the resource `intake.*` and `charting.*`
describe (see [Intake](#intake) and [Charting](#charting)), and `intake_id` points at it.

The three types carry the same data shape. Only `1.0` exists, so a default subscription and a
wildcard both receive what is emitted. Selections are expanded when the endpoint is saved: an
endpoint registered with `*` before these types existed does not receive them until its
subscriptions are updated, and `intake.*` and `charting.*` never cover them; add
`requested_form_completion.*` or the three types.

> [tab] 1.0 (default)
>
> | Field | Type | Required | Nullable | Description |
> | - | - | - | - | - |
> | `resource_id` | string | Yes | No | Id of the form request. The same on `.created` and every later `.updated` and `.deleted` for that request. |
> | `resource_organization_id` | string | Yes | Yes | Opaque reference to the organization that holds the record. It is not your OpenLoop organization id. |
> | `status` | string | Yes | No | Canonical status, one of `not_started`, `in_progress`, `completed`, `unknown`; see below. |
> | `patient_ref` | string | Yes | Yes | The patient asked to fill out the form. It is not guaranteed to be a `/v0.1` patient id; see [Correlating events to your records](#correlating-events-to-your-records). `null` on `.deleted`. |
> | `provider_ref` | string | Yes | Yes | The provider who sent the request. `null` on `.deleted`. |
> | `questionnaire_ref` | string | Yes | Yes | The form requested: the same form id the `intake.*` (`1.0`) / `charting.*` events for the submitted form carry in `questionnaire_ref`. `null` on `.deleted`. |
> | `intake_id` | string | Yes | Yes | The patient's form: the `resource_id` of the `intake.*` (`1.0`) or `charting.*` events for it after it is submitted. Set once the patient opens the form; `null` before that and on `.deleted`. |
> | `emr_patient_id` | string | No | No | The patient's id, the `id` that `GET /v0.1/patients/{id}` takes, when known; omitted otherwise, never `null`, and absent on `.deleted`. See [Correlating events to your records](#correlating-events-to-your-records). |
> | `extra_fields` | object | Yes | No | Two keys, below. Not a passthrough. |
> | `extra_fields.item_type` | string | Yes | Yes | The kind of item requested, as the source labels it. Treat it as an opaque string; do not branch on its values. `null` on `.deleted`. |
> | `extra_fields.changed_fields` | array | Yes | No | The names of the fields that changed in the source record. Informational only; do not rely on specific values. |

| `status` | Meaning |
| - | - |
| `not_started` | The request was sent and the patient has not opened the form. |
| `in_progress` | The patient opened the form. |
| `completed` | The patient submitted the form. |
| `unknown` | The status could not be determined. Every `requested_form_completion.deleted` carries it. |

The set is fixed for `1.0`: a new value would come with a new `eventVersion`. A request's
`completed` means the patient submitted the form, not that the form is locked: the form's own
`intake.*` / `charting.*` events carry its `status`, and `intake.completed` / `charting.completed`
fire only when the form is locked.

`requested_form_completion.updated` fires only when `status` changes: when the patient first opens
the form (`in_progress`) and when they submit it (`completed`). Saving a draft sends no `.updated`.
A submit is usually followed shortly by the `intake.created` (at `1.0`) event for an intake form,
or the `charting.created` event for any other form (see [Charting](#charting)),
whose `resource_id` is this event's `intake_id`. That event is not guaranteed for every
organization, and deliveries are not ordered, so either can arrive first: do not wait for it before
acting on a request's `completed`.

`requested_form_completion.deleted` keeps `resource_id` and `resource_organization_id`. Every other
reference and `extra_fields.item_type` are `null`, `status` is `unknown`, and `emr_patient_id` is
absent. Route on the event type, not on `status`.

Dedupe on the envelope `id`, as for every event. Delivery is at least once and not ordered, and
nothing in `data` orders two events for the same `resource_id`: there is no `created_at` or
`updated_at`, and unlike intake and charting there is no `organization` object.

```json requested_form_completion.created theme={null}
{
  "id": "7c3e9a1f5b...d08",
  "type": "requested_form_completion.created",
  "eventVersion": "1.0",
  "occurredAt": "2026-10-20T15:20:06.000Z",
  "data": {
    "resource_id": "3307215",
    "resource_organization_id": "102938",
    "status": "not_started",
    "patient_ref": "6650172",
    "provider_ref": "5512093",
    "questionnaire_ref": "1975412",
    "intake_id": null,
    "emr_patient_id": "b7d4e1a8-2c5f-4a9b-8e3d-6f1a4c7b0e92",
    "extra_fields": {
      "item_type": "<opaque string>",
      "changed_fields": []
    }
  }
}
```

```json requested_form_completion.updated theme={null}
{
  "id": "a4d6f8b0c2...e71",
  "type": "requested_form_completion.updated",
  "eventVersion": "1.0",
  "occurredAt": "2026-10-20T15:43:58.000Z",
  "data": {
    "resource_id": "3307215",
    "resource_organization_id": "102938",
    "status": "completed",
    "patient_ref": "6650172",
    "provider_ref": "5512093",
    "questionnaire_ref": "1975412",
    "intake_id": "2281904",
    "emr_patient_id": "b7d4e1a8-2c5f-4a9b-8e3d-6f1a4c7b0e92",
    "extra_fields": {
      "item_type": "<opaque string>",
      "changed_fields": ["<source field name>"]
    }
  }
}
```

```json requested_form_completion.deleted theme={null}
{
  "id": "e8a0c2d4f6...193",
  "type": "requested_form_completion.deleted",
  "eventVersion": "1.0",
  "occurredAt": "2026-10-21T10:02:47.000Z",
  "data": {
    "resource_id": "3307288",
    "resource_organization_id": "102938",
    "status": "unknown",
    "patient_ref": null,
    "provider_ref": null,
    "questionnaire_ref": null,
    "intake_id": null,
    "extra_fields": {
      "item_type": null,
      "changed_fields": []
    }
  }
}
```

> [!NOTE]
>
> Treat every `requested_form_completion.*` event as PHI: `patient_ref` ties the request to a patient.
> The events carry references, `status` and the two `extra_fields` keys only: no form name, no
> answers, and no names or contact details for the patient or provider.

### Invoice

`invoice.paid` fires when an invoice is paid in full — `status` is `paid` and `paid_date` is
populated. This is the event to key settlement on; it carries the canonical invoice snapshot (amounts,
status, line items, billing customer) at the moment payment completed.

`invoice.created`, `invoice.finalized`, `invoice.payment_succeeded`, `invoice.payment_failed`,
`invoice.payment_action_required`, `invoice.paid`, `invoice.voided` and `invoice.marked_uncollectible`
carry the same data shape. Each is a snapshot of the invoice when the event occurred; read `status` and
the timestamps from the payload, not from the event name alone:

| Event | Sent when | What the snapshot shows |
| - | - | - |
| `invoice.created` | An invoice is created | `status` is the state at creation, often `draft`. |
| `invoice.finalized` | An invoice is finalized | `status` is `open` and `finalized_at` is set. |
| `invoice.payment_succeeded` | A payment attempt succeeds | Sent together with `invoice.paid` for the same payment. Key settlement on `invoice.paid` so you do not act twice. |
| `invoice.payment_failed` | A payment attempt fails | `paid_date` is `null` and `status` is not `paid` (typically `open`). `total_paid` holds what was paid before the failure, so it does not cover `amount_due_cents`. `attempt_count` counts the attempts so far; `next_payment_attempt` is the next scheduled retry, or `null` when no retry is scheduled. |
| `invoice.payment_action_required` | A payment needs the customer to act, e.g. to authenticate | `paid_date` is `null` and `status` is not `paid`. |
| `invoice.paid` | An invoice is paid in full | `status` is `paid` and `paid_date` is set. |
| `invoice.voided` | An invoice is voided | `status` is `void` and `voided_at` is set. |
| `invoice.marked_uncollectible` | An invoice is marked uncollectible | `status` is `uncollectible` and `marked_uncollectible_at` is set. |

> [tab] 2.0
>
> | Field | Type | Required | Nullable | Description |
> | - | - | - | - | - |
> | `livemode` | boolean | Yes | No | Provider live (production) mode vs test mode. |
> | `occurred_at` | string | Yes | No | When the change occurred at the provider (ISO-8601). |
> | `extra_fields` | object | No | No | Free-form provider passthrough (no fixed schema). |
> | `config` | object | Yes | No | OpenLoop payments configuration context. |
> | `config.config_id` | string | Yes | No | OpenLoop payments config id. |
> | `config.provider_account_id` | string | Yes | Yes | Provider connected-account id. |
> | `config.payment_group` | string | Yes | Yes | Payment group the config belongs to, e.g. `A`, `B` or `C`. |
> | `billing_customer` | object | Yes | No | Billing customer reference. |
> | `billing_customer.provider_customer_id` | string | Yes | Yes | Provider customer id. |
> | `billing_customer.email` | string | Yes | Yes | Customer billing email (PII). |
> | `provider_invoice_id` | string | Yes | No | Provider invoice id. |
> | `provider_subscription_id` | string | Yes | Yes | Related subscription id, if any. |
> | `number` | string | Yes | Yes | Human-readable invoice number. |
> | `description` | string | Yes | Yes | Invoice description. |
> | `status` | string | Yes | No | Canonical invoice status, one of `draft`, `open`, `paid`, `uncollectible`, `void`, `unknown`. |
> | `currency` | string | Yes | No | ISO currency code. |
> | `paid_date` | string | Yes | Yes | When the invoice was paid; set on `invoice.paid`. |
> | `due_date` | string | Yes | Yes | Invoice due date. |
> | `total_amount` | number | Yes | No | Invoice total (provider units). |
> | `total_paid` | number | Yes | No | Amount paid. |
> | `period_end` | string | Yes | No | Billing period end. |
> | `period_start` | string | Yes | No | Billing period start. |
> | `billing_reason` | string | Yes | Yes | Why the invoice was created; enum `PaymentsInvoiceBillingReason` (`automatic_pending_invoice_item_invoice`, `manual`, `quote_accept`, `subscription`, `subscription_create`, `subscription_cycle`, `subscription_threshold`, `subscription_update`, `upcoming`, `unknown`). |
> | `collection_method` | string | Yes | No | One of `charge_automatically`, `send_invoice`, `unknown`. |
> | `hosted_invoice_url` | string | Yes | Yes | Hosted invoice page URL. |
> | `invoice_pdf` | string | Yes | Yes | Invoice PDF URL. |
> | `discounts` | array | Yes | No | Invoice-level discounts. |
> | `discounts[].provider_discount_id` | string | Yes | No | Provider discount id. |
> | `lines` | array | Yes | No | Invoice line items. |
> | `lines[].provider_product_id` | string | Yes | Yes | Provider product id for the line. |
> | `lines[].provider_price_id` | string | Yes | Yes | Provider price id for the line. |
> | `lines[].product` | object | Yes | Yes | Resolved product for the line, or `null`. |
> | `lines[].product.name` | string | Yes | Yes | Product name. |
> | `lines[].product.description` | string | Yes | Yes | Product description. |
> | `lines[].product.status` | string | Yes | No | One of `active`, `archived`, `unknown`. |
> | `lines[].product.program_code` | string | Yes | Yes | OpenLoop program code. |
> | `lines[].product.program_id` | string | Yes | Yes | OpenLoop program id. |
> | `lines[].product.metadata` | object | Yes | No | Free-form `string → string` product metadata. |
> | `lines[].billing_interval` | string | Yes | Yes | One of `day`, `week`, `month`, `year`, `unknown`. |
> | `lines[].billing_interval_count` | number | Yes | Yes | Intervals per billing cycle. |
> | `lines[].currency` | string | Yes | No | Line currency. |
> | `lines[].description` | string | Yes | Yes | Line description. |
> | `lines[].amount_cents` | number | Yes | No | Line amount, in cents. |
> | `lines[].quantity` | number | Yes | No | Line quantity. |
> | `lines[].discounts` | array | Yes | No | Line-level discounts. |
> | `lines[].discounts[].provider_discount_id` | string | Yes | No | Provider discount id. |
> | `metadata` | object | Yes | No | Free-form `string → string` invoice metadata. |
> | `created` | string | Yes | No | Invoice creation timestamp. |
> | `amount_due_cents` | number | Yes | No | Amount due, in cents. |
> | `amount_remaining_cents` | number | Yes | No | Amount remaining, in cents. |
> | `subtotal_cents` | number | Yes | No | Subtotal, in cents. |
> | `tax_amount_cents` | number | Yes | Yes | Tax amount, in cents. |
> | `discount_amount_cents` | number | Yes | Yes | Discount amount, in cents. |
> | `receipt_number` | string | Yes | Yes | Receipt number. |
> | `finalized_at` | string | Yes | Yes | When the invoice was finalized. |
> | `voided_at` | string | Yes | Yes | When the invoice was voided. |
> | `marked_uncollectible_at` | string | Yes | Yes | When marked uncollectible. |
> | `attempt_count` | number | Yes | No | Number of payment attempts. |
> | `next_payment_attempt` | string | Yes | Yes | Next scheduled payment attempt. |
> | `provider_default_payment_method_id` | string | Yes | Yes | Default payment method id at the provider. |
> | `amount_overpaid_cents` | number | Yes | Yes | Amount overpaid, in cents. |
> | `amount_shipping_cents` | number | Yes | Yes | Shipping amount, in cents. |
> | `total_excluding_tax_cents` | number | Yes | Yes | Total excluding tax, in cents. |
> | `subtotal_excluding_tax_cents` | number | Yes | Yes | Subtotal excluding tax, in cents. |
> | `starting_balance_cents` | number | Yes | Yes | Customer starting balance applied, in cents. |
> | `ending_balance_cents` | number | Yes | Yes | Customer ending balance, in cents. |
> | `effective_at` | string | Yes | Yes | Effective timestamp of the invoice. |
> | `changed_fields` | array | Yes | No | Names of the invoice fields that changed on this event (enum `PaymentsInvoiceChangedFieldV2`). |
> | `previous` | object | No | No | Prior values of the changed fields (same keys as above, only the changed ones present). |

`extra_fields` is a free-form provider passthrough (raw provider fields with no fixed schema), not
part of the versioned contract.

```json Example: invoice.paid theme={null}
{
  "id": "dd8b2b068d...c1ad",
  "type": "invoice.paid",
  "eventVersion": "2.0",
  "occurredAt": "2026-10-21T12:00:04.000Z",
  "data": {
    "livemode": false,
    "occurred_at": "2026-10-21T12:00:04.000Z",
    "config": {
      "config_id": "cfg_01JAB3C4D5",
      "provider_account_id": "acct_1PqR2sT3uV4wX5yZ",
      "payment_group": "A"
    },
    "billing_customer": {
      "provider_customer_id": "cus_RxW8a1B2c3D4e5",
      "email": "jane.sample@example.com"
    },
    "provider_invoice_id": "in_1QaZ9yX8wV7uT6sR",
    "provider_subscription_id": "sub_1QaZ1bC2dE3fG4hI",
    "number": "ACME-0042-0003",
    "description": null,
    "status": "paid",
    "currency": "usd",
    "paid_date": "2026-10-21T12:00:03.000Z",
    "due_date": null,
    "total_amount": 19900,
    "total_paid": 19900,
    "period_end": "2026-10-21T12:00:00.000Z",
    "period_start": "2026-09-21T12:00:00.000Z",
    "billing_reason": "subscription_cycle",
    "collection_method": "charge_automatically",
    "hosted_invoice_url": "https://invoice.example.com/i/acct_1PqR2sT3uV4wX5yZ/test_YWNjd",
    "invoice_pdf": "https://pay.example.com/invoice/acct_1PqR2sT3uV4wX5yZ/test_YWNjd/pdf",
    "discounts": [],
    "lines": [
      {
          "provider_product_id": "prod_RxW8mT2kLq4N",
          "provider_price_id": "price_1QaB2cD3eF4gH5iJ",
          "product": {
            "name": "Weight management membership",
            "description": "Monthly membership",
            "status": "active",
            "program_code": "MWL",
            "program_id": "prg_01HZX3",
            "metadata": {}
          },
          "billing_interval": "month",
          "billing_interval_count": 1,
          "currency": "usd",
          "description": "1 × Weight management membership (at $199.00 / month)",
          "amount_cents": 19900,
          "quantity": 1,
          "discounts": []
        }
    ],
    "metadata": {},
    "created": "2026-10-21T11:00:02.000Z",
    "amount_due_cents": 19900,
    "amount_remaining_cents": 0,
    "subtotal_cents": 19900,
    "tax_amount_cents": null,
    "discount_amount_cents": null,
    "receipt_number": null,
    "finalized_at": "2026-10-21T12:00:01.000Z",
    "voided_at": null,
    "marked_uncollectible_at": null,
    "attempt_count": 1,
    "next_payment_attempt": null,
    "provider_default_payment_method_id": null,
    "amount_overpaid_cents": 0,
    "amount_shipping_cents": 0,
    "total_excluding_tax_cents": 19900,
    "subtotal_excluding_tax_cents": 19900,
    "starting_balance_cents": 0,
    "ending_balance_cents": 0,
    "effective_at": "2026-10-21T12:00:01.000Z",
    "changed_fields": ["status", "paid_date", "total_paid", "amount_remaining_cents"],
    "previous": {
      "status": "open",
      "paid_date": null,
      "total_paid": 0,
      "amount_remaining_cents": 19900
    },
    "extra_fields": {}
  }
}
```

Amounts are in the currency's smallest unit (`19900` is \$199.00), and timestamps are ISO-8601
strings.

### Subscription

`subscription.created` fires when a subscription is created and `subscription.updated` when it changes
(status, items, schedule). On `subscription.created` the `previous` object is absent; on
`subscription.updated`, `changed_fields` names what changed and `previous` holds the prior values.

`subscription.canceled` fires when a subscription is canceled and ends: `status` is `canceled`, and
`canceled_at` and `ended_at` are set. `subscription.paused` and `subscription.resumed` fire when the
subscription's `status` changes to and from `paused`. `subscription.trial_will_end` fires three days
before `trial_end`, or at once when a trial is ended early.

> [!NOTE]
>
> A pause made with `POST /v0.1/subscriptions/{provider_subscription_id}/pauses` pauses payment
> collection; it does not change `status`. It arrives as `subscription.updated`, with `paused` set to
> `true` and `resumes_at` set to the resume date when one was given, and never as `subscription.paused`
> or `subscription.resumed`. To track those pauses, listen to `subscription.updated`.

`subscription.created`, `subscription.updated`, `subscription.canceled`, `subscription.paused`,
`subscription.resumed` and `subscription.trial_will_end` carry the same data shape.

> [tab] 2.0
>
> | Field | Type | Required | Nullable | Description |
> | - | - | - | - | - |
> | `livemode` | boolean | Yes | No | Provider live vs test mode. |
> | `occurred_at` | string | Yes | No | When the change occurred at the provider. |
> | `extra_fields` | object | No | No | Free-form provider passthrough. |
> | `config` | object | Yes | No | OpenLoop payments configuration context. |
> | `config.config_id` | string | Yes | No | OpenLoop payments config id. |
> | `config.provider_account_id` | string | Yes | Yes | Provider connected-account id. |
> | `config.payment_group` | string | Yes | Yes | Payment group the config belongs to, e.g. `A`, `B` or `C`. |
> | `billing_customer` | object | Yes | No | Billing customer reference. |
> | `billing_customer.provider_customer_id` | string | Yes | Yes | Provider customer id. |
> | `billing_customer.email` | string | Yes | Yes | Customer billing email (PII). |
> | `provider_subscription_id` | string | Yes | No | Provider subscription id. |
> | `status` | string | Yes | No | One of `active`, `past_due`, `unpaid`, `canceled`, `incomplete`, `incomplete_expired`, `trialing`, `paused`, `unknown`. |
> | `description` | string | Yes | Yes | Subscription description. |
> | `items` | array | Yes | No | Subscription line items. |
> | `items[].provider_item_id` | string | Yes | No | Provider subscription-item id. |
> | `items[].quantity` | number | Yes | No | Item quantity. |
> | `items[].metadata` | object | Yes | Yes | Free-form item metadata map, or `null`. |
> | `items[].price` | object | Yes | Yes | Price for the item, or `null`. |
> | `items[].price.provider_price_id` | string | Yes | No | Provider price id. |
> | `items[].price.provider_product_id` | string | Yes | No | Provider product id. |
> | `items[].price.currency` | string | Yes | No | Price currency. |
> | `items[].price.amount_cents` | number | Yes | Yes | Unit amount, in cents. |
> | `items[].price.active` | boolean | Yes | Yes | Whether the price is active. |
> | `items[].price.billing_scheme` | string | Yes | Yes | One of `per_unit`, `tiered`, `unknown`. |
> | `items[].price.created` | string | Yes | Yes | Price creation timestamp. |
> | `items[].price.recurring` | object | Yes | Yes | Recurring cadence, or `null` for one-time. |
> | `items[].price.recurring.interval` | string | Yes | No | One of `day`, `week`, `month`, `year`, `unknown`. |
> | `items[].price.recurring.interval_count` | number | Yes | No | Intervals per cycle. |
> | `items[].product` | object | Yes | Yes | Resolved product for the item, or `null`. |
> | `items[].product.name` | string | Yes | Yes | Product name. |
> | `items[].product.description` | string | Yes | Yes | Product description. |
> | `items[].product.program_code` | string | Yes | Yes | OpenLoop program code. |
> | `items[].product.program_id` | string | Yes | Yes | OpenLoop program id. |
> | `items[].product.metadata` | object | Yes | No | Free-form product metadata map. |
> | `items[].current_period_end` | string | Yes | Yes | Item current period end. |
> | `items[].current_period_start` | string | Yes | Yes | Item current period start. |
> | `items[].created` | string | Yes | Yes | Item creation timestamp. |
> | `cancellation_details` | object | Yes | Yes | Cancellation detail block, or `null`. |
> | `cancellation_details.comment` | string | Yes | Yes | Free-text cancellation comment. |
> | `cancellation_details.feedback` | string | Yes | Yes | Enum `PaymentsCancellationFeedbackV2` (`customer_service`, `low_quality`, `missing_features`, `other`, `switched_service`, `too_complex`, `too_expensive`, `unused`, `unknown`). |
> | `cancellation_details.reason` | string | Yes | Yes | Enum `PaymentsCancellationReasonV2` (`canceled_by_retention_policy`, `cancellation_requested`, `payment_disputed`, `payment_failed`, `unknown`). |
> | `cancel_at_period_end` | boolean | Yes | No | Whether it cancels at period end. |
> | `cancel_at` | string | Yes | Yes | Scheduled cancellation timestamp. |
> | `canceled_at` | string | Yes | Yes | When it was canceled. |
> | `ended_at` | string | Yes | Yes | When it ended. |
> | `paused` | boolean | Yes | No | Whether it is paused. |
> | `resumes_at` | string | Yes | Yes | When a paused subscription resumes. |
> | `metadata` | object | Yes | No | Free-form subscription metadata map. |
> | `start_date` | string | Yes | No | Subscription start date. |
> | `trial_start` | string | Yes | Yes | Trial start timestamp. |
> | `trial_end` | string | Yes | Yes | Trial end timestamp. |
> | `collection_method` | string | Yes | No | One of `charge_automatically`, `send_invoice`, `unknown`. |
> | `created` | string | Yes | No | Subscription creation timestamp. |
> | `last_invoice` | object | Yes | Yes | Reference to the latest invoice, or `null`. |
> | `last_invoice.provider_invoice_id` | string | Yes | No | Provider invoice id of the latest invoice. |
> | `billing_cycle_anchor` | string | Yes | No | Billing cycle anchor timestamp. |
> | `provider_default_payment_method_id` | string | Yes | Yes | Default payment method id at the provider. |
> | `provider_schedule_id` | string | Yes | Yes | Provider subscription-schedule id, if any. |
> | `currency` | string | Yes | No | Subscription currency. |
> | `days_until_due` | number | Yes | Yes | Days until invoice due (`send_invoice`). |
> | `pause_collection_behavior` | string | Yes | Yes | One of `keep_as_draft`, `mark_uncollectible`, `void`, `unknown`. |
> | `changed_fields` | array | Yes | No | Names of the subscription fields that changed on this event (enum `PaymentsSubscriptionChangedFieldV2`). |
> | `previous` | object | No | No | Prior values of the changed fields (absent on create). |

`extra_fields` is a free-form provider passthrough (raw provider fields with no fixed schema), not
part of the versioned contract.

```json subscription.created theme={null}
{
  "id": "71b3d5f7a9...0c4",
  "type": "subscription.created",
  "eventVersion": "2.0",
  "occurredAt": "2026-10-21T12:00:02.000Z",
  "data": {
    "livemode": false,
    "occurred_at": "2026-10-21T12:00:02.000Z",
    "config": {
      "config_id": "cfg_01JAB3C4D5",
      "provider_account_id": "acct_1PqR2sT3uV4wX5yZ",
      "payment_group": "A"
    },
    "billing_customer": {
      "provider_customer_id": "cus_RxW8a1B2c3D4e5",
      "email": "jane.sample@example.com"
    },
    "provider_subscription_id": "sub_1QaZ1bC2dE3fG4hI",
    "status": "active",
    "description": null,
    "items": [
      {
        "provider_item_id": "si_RxW8b2C3d4E5f6",
        "quantity": 1,
        "metadata": {},
        "price": {
          "provider_price_id": "price_1QaB2cD3eF4gH5iJ",
          "provider_product_id": "prod_RxW8mT2kLq4N",
          "currency": "usd",
          "amount_cents": 19900,
          "active": true,
          "billing_scheme": "per_unit",
          "created": "2026-08-01T10:00:00.000Z",
          "recurring": { "interval": "month", "interval_count": 1 }
        },
        "product": {
          "name": "Weight management membership",
          "description": "Monthly membership",
          "program_code": "MWL",
          "program_id": "prg_01HZX3",
          "metadata": {}
        },
        "current_period_end": "2026-11-21T12:00:00.000Z",
        "current_period_start": "2026-10-21T12:00:00.000Z",
        "created": "2026-10-21T12:00:00.000Z"
      }
    ],
    "cancellation_details": { "comment": null, "feedback": null, "reason": null },
    "cancel_at_period_end": false,
    "cancel_at": null,
    "canceled_at": null,
    "ended_at": null,
    "paused": false,
    "resumes_at": null,
    "metadata": {},
    "start_date": "2026-10-21T12:00:00.000Z",
    "trial_start": null,
    "trial_end": null,
    "collection_method": "charge_automatically",
    "created": "2026-10-21T12:00:00.000Z",
    "last_invoice": { "provider_invoice_id": "in_1QaZ9yX8wV7uT6sR" },
    "billing_cycle_anchor": "2026-10-21T12:00:00.000Z",
    "provider_default_payment_method_id": "pm_1QaZ5kL6mN7oP8qR",
    "provider_schedule_id": null,
    "currency": "usd",
    "days_until_due": null,
    "pause_collection_behavior": null,
    "changed_fields": [],
    "extra_fields": {}
  }
}
```

```json subscription.updated theme={null}
{
  "id": "2e4a6c8e0b...95d",
  "type": "subscription.updated",
  "eventVersion": "2.0",
  "occurredAt": "2026-10-22T09:30:11.000Z",
  "data": {
    "livemode": false,
    "occurred_at": "2026-10-22T09:30:11.000Z",
    "config": {
      "config_id": "cfg_01JAB3C4D5",
      "provider_account_id": "acct_1PqR2sT3uV4wX5yZ",
      "payment_group": "A"
    },
    "billing_customer": {
      "provider_customer_id": "cus_RxW8a1B2c3D4e5",
      "email": "jane.sample@example.com"
    },
    "provider_subscription_id": "sub_1QaZ1bC2dE3fG4hI",
    "status": "active",
    "description": null,
    "items": [
      {
        "provider_item_id": "si_RxW8b2C3d4E5f6",
        "quantity": 1,
        "metadata": {},
        "price": {
          "provider_price_id": "price_1QaB2cD3eF4gH5iJ",
          "provider_product_id": "prod_RxW8mT2kLq4N",
          "currency": "usd",
          "amount_cents": 19900,
          "active": true,
          "billing_scheme": "per_unit",
          "created": "2026-08-01T10:00:00.000Z",
          "recurring": { "interval": "month", "interval_count": 1 }
        },
        "product": {
          "name": "Weight management membership",
          "description": "Monthly membership",
          "program_code": "MWL",
          "program_id": "prg_01HZX3",
          "metadata": {}
        },
        "current_period_end": "2026-11-21T12:00:00.000Z",
        "current_period_start": "2026-10-21T12:00:00.000Z",
        "created": "2026-10-21T12:00:00.000Z"
      }
    ],
    "cancellation_details": { "comment": null, "feedback": "too_expensive", "reason": "cancellation_requested" },
    "cancel_at_period_end": true,
    "cancel_at": "2026-11-21T12:00:00.000Z",
    "canceled_at": null,
    "ended_at": null,
    "paused": false,
    "resumes_at": null,
    "metadata": {},
    "start_date": "2026-10-21T12:00:00.000Z",
    "trial_start": null,
    "trial_end": null,
    "collection_method": "charge_automatically",
    "created": "2026-10-21T12:00:00.000Z",
    "last_invoice": { "provider_invoice_id": "in_1QaZ9yX8wV7uT6sR" },
    "billing_cycle_anchor": "2026-10-21T12:00:00.000Z",
    "provider_default_payment_method_id": "pm_1QaZ5kL6mN7oP8qR",
    "provider_schedule_id": null,
    "currency": "usd",
    "days_until_due": null,
    "pause_collection_behavior": null,
    "changed_fields": ["cancel_at_period_end", "cancel_at", "cancellation_details"],
    "previous": {
      "cancel_at_period_end": false,
      "cancel_at": null,
      "cancellation_details": { "comment": null, "feedback": null, "reason": null }
    },
    "extra_fields": {}
  }
}
```

The `subscription.updated` example is a cancellation scheduled for the end of the period:
`status` is still `active`, and `changed_fields` and `previous` show what moved.

### Credit note

`credit_note.created` fires when a credit note is created and `credit_note.voided` when one is voided
(`status` is `void`). A refund issued with `POST /v0.1/invoices/{provider_invoice_id}/refunds` creates
a credit note, and the credit note fields below mirror that endpoint's response.

> [!NOTE]
>
> **Listen to `credit_note.*` for refunds.** Refunds are published as `credit_note.created` and
> `credit_note.voided` at `2.0`. `refund.*` is not published at `2.0`; do not subscribe to it for
> refunds.

On `credit_note.created`, `changed_fields` is `[]` and `previous` is absent. On `credit_note.voided`,
`changed_fields` names what changed (e.g. `["status"]`) and `previous` holds the prior values (e.g.
`{ "status": "issued" }`), or `changed_fields` is `[]` when the event is a snapshot with no recorded
change. Read `status` rather than relying on `previous`.

`credit_note.created` and `credit_note.voided` carry the same data shape.

> [tab] 2.0
>
> | Field | Type | Required | Nullable | Description |
> | - | - | - | - | - |
> | `livemode` | boolean | Yes | No | Provider live vs test mode. |
> | `occurred_at` | string | Yes | No | When the change occurred at the provider (ISO-8601). |
> | `extra_fields` | object | No | No | Free-form provider passthrough. |
> | `config` | object | Yes | No | OpenLoop payments configuration context. |
> | `config.config_id` | string | Yes | No | OpenLoop payments config id. |
> | `config.provider_account_id` | string | Yes | Yes | Provider connected-account id. |
> | `config.payment_group` | string | Yes | Yes | Payment group the config belongs to, e.g. `A`, `B` or `C`. |
> | `billing_customer` | object | Yes | No | Billing customer reference. |
> | `billing_customer.provider_customer_id` | string | Yes | Yes | Provider customer id of the credited invoice. |
> | `billing_customer.email` | string | Yes | Yes | Customer billing email (PII); `null` when it cannot be resolved. |
> | `provider_credit_note_id` | string | Yes | No | Provider credit note id. |
> | `provider_invoice_id` | string | Yes | No | Id of the invoice the credit note applies to. |
> | `status` | string | Yes | No | One of `issued`, `void`, `unknown`. |
> | `amount` | number | Yes | No | Credit note total, in cents. |
> | `currency` | string | Yes | No | ISO currency code. |
> | `reason` | string | Yes | Yes | One of `duplicate`, `fraudulent`, `order_change`, `product_unsatisfactory`, `unknown`. |
> | `description` | string | Yes | Yes | Free-text note on the credit note (the refund request's `description`). |
> | `credit_note_pdf` | string | Yes | Yes | Credit note PDF URL. |
> | `created` | string | Yes | No | Credit note creation timestamp. |
> | `changed_fields` | array | Yes | No | Names of the credit note fields that changed on this event (enum `PaymentsCreditNoteChangedFieldV2`: the credit note field names above, from `provider_credit_note_id` to `created`). |
> | `previous` | object | No | No | Prior values of the changed fields (absent on create). |

Every timestamp is an ISO-8601 string; the REST API returns epoch seconds under the same names.

### Dispute

`dispute.created` fires when a customer disputes a charge, `dispute.updated` when a dispute changes
(for example, evidence is submitted), `dispute.funds_withdrawn` when the disputed funds are withdrawn,
`dispute.funds_reinstated` when they are returned, and `dispute.closed` when the dispute ends. On
`dispute.closed`, `status` gives the result: `won`, `lost` or `warning_closed`.

> [!NOTE]
>
> **Dispute evidence is not in the event.** The evidence holds the customer's personal data, so it is
> never published. `evidence_details` (the deadline and submission state) is included.

A dispute carries no customer, so `billing_customer.provider_customer_id` and
`billing_customer.email` are always `null`. To find the customer, read the payment intent with
`GET /v0.1/intents/payments/{provider_payment_intent_id}`.

On `dispute.created`, `changed_fields` is `[]` and `previous` is absent. On the other dispute types,
`changed_fields` names what changed (e.g. `["status"]`) and `previous` holds the prior values, or
`changed_fields` is `[]` when the event is a snapshot with no recorded change.

`dispute.created`, `dispute.updated`, `dispute.funds_withdrawn`, `dispute.funds_reinstated` and
`dispute.closed` carry the same data shape.

> [tab] 2.0
>
> | Field | Type | Required | Nullable | Description |
> | - | - | - | - | - |
> | `livemode` | boolean | Yes | No | Provider live vs test mode. |
> | `occurred_at` | string | Yes | No | When the change occurred at the provider (ISO-8601). |
> | `extra_fields` | object | No | No | Free-form provider passthrough. |
> | `config` | object | Yes | No | OpenLoop payments configuration context. |
> | `config.config_id` | string | Yes | No | OpenLoop payments config id. |
> | `config.provider_account_id` | string | Yes | Yes | Provider connected-account id. |
> | `config.payment_group` | string | Yes | Yes | Payment group the config belongs to, e.g. `A`, `B` or `C`. |
> | `billing_customer` | object | Yes | No | Billing customer reference. |
> | `billing_customer.provider_customer_id` | string | Yes | Yes | Always `null` on dispute events. |
> | `billing_customer.email` | string | Yes | Yes | Always `null` on dispute events. |
> | `provider_dispute_id` | string | Yes | No | Provider dispute id. |
> | `provider_payment_intent_id` | string | Yes | Yes | Payment intent of the disputed charge; `null` when the charge has none. |
> | `provider_charge_id` | string | Yes | No | Provider id of the disputed charge. |
> | `amount_cents` | number | Yes | No | Disputed amount, in cents. |
> | `currency` | string | Yes | No | ISO currency code. |
> | `reason` | string | Yes | No | One of `bank_cannot_process`, `check_returned`, `credit_not_processed`, `customer_initiated`, `debit_not_authorized`, `duplicate`, `fraudulent`, `general`, `incorrect_account_details`, `insufficient_funds`, `noncompliant`, `product_not_received`, `product_unacceptable`, `subscription_canceled`, `unrecognized`, `unknown`. |
> | `status` | string | Yes | No | One of `warning_needs_response`, `warning_under_review`, `warning_closed`, `needs_response`, `under_review`, `won`, `lost`, `prevented`, `unknown`. |
> | `evidence_details` | object | Yes | No | Evidence deadline and submission state. Carries no evidence content. |
> | `evidence_details.due_by` | string | Yes | Yes | Deadline to submit evidence; `null` when none applies. |
> | `evidence_details.has_evidence` | boolean | Yes | No | Whether evidence has been added. |
> | `evidence_details.past_due` | boolean | Yes | No | Whether the evidence deadline has passed. |
> | `evidence_details.submission_count` | number | Yes | No | Number of times evidence has been submitted. |
> | `is_charge_refundable` | boolean | Yes | No | Whether the disputed charge can still be refunded. |
> | `created` | string | Yes | No | Dispute creation timestamp. |
> | `changed_fields` | array | Yes | No | Names of the dispute fields that changed on this event (enum `PaymentsDisputeChangedFieldV2`: the dispute field names above, from `provider_dispute_id` to `created`). |
> | `previous` | object | No | No | Prior values of the changed fields (absent on create). |

Every timestamp is an ISO-8601 string; the REST API returns epoch seconds under the same names.

### Checkout session

`checkout.session.completed` fires when a customer completes a checkout session and
`checkout.session.expired` when a session expires before it completes. For a payment method that
settles later, `checkout.session.completed` arrives with `payment_status` `unpaid`, then
`checkout.session.async_payment_succeeded` or `checkout.session.async_payment_failed` reports the
result.

`provider_checkout_session_id` is the id that `POST /v0.1/checkouts/sessions` returns. The event
describes the session's outcome only: it never carries the session's secrets or its payable link, and
it carries no customer details except `billing_customer.email`.

Every checkout session event is a snapshot: `changed_fields` is always `[]` and `previous` is absent.
An unrecognized `type`, `status` or `payment_status` is sent as `unknown`.

`checkout.session.completed`, `checkout.session.expired`, `checkout.session.async_payment_succeeded`
and `checkout.session.async_payment_failed` carry the same data shape.

> [tab] 2.0
>
> | Field | Type | Required | Nullable | Description |
> | - | - | - | - | - |
> | `livemode` | boolean | Yes | No | Provider live vs test mode. |
> | `occurred_at` | string | Yes | No | When the change occurred at the provider (ISO-8601). |
> | `extra_fields` | object | No | No | Free-form provider passthrough. |
> | `config` | object | Yes | No | OpenLoop payments configuration context. |
> | `config.config_id` | string | Yes | No | OpenLoop payments config id. |
> | `config.provider_account_id` | string | Yes | Yes | Provider connected-account id. |
> | `config.payment_group` | string | Yes | Yes | Payment group the config belongs to, e.g. `A`, `B` or `C`. |
> | `billing_customer` | object | Yes | No | Billing customer reference. |
> | `billing_customer.provider_customer_id` | string | Yes | Yes | Provider customer id; `null` when the session has no customer. |
> | `billing_customer.email` | string | Yes | Yes | Email the customer gave at checkout (PII); `null` when none was given. |
> | `provider_checkout_session_id` | string | Yes | No | Provider checkout session id. |
> | `type` | string | Yes | No | Session type, one of `payment`, `setup`, `subscription`, `unknown`. |
> | `status` | string | Yes | No | One of `open`, `complete`, `expired`, `unknown`. |
> | `payment_status` | string | Yes | No | One of `paid`, `unpaid`, `no_payment_required`, `unknown`. |
> | `currency` | string | Yes | Yes | ISO currency code. |
> | `amount_subtotal_cents` | number | Yes | Yes | Subtotal before discounts and taxes, in cents. |
> | `amount_total_cents` | number | Yes | Yes | Total after discounts and taxes, in cents. |
> | `provider_subscription_id` | string | Yes | Yes | Subscription the session created (`subscription` type). |
> | `provider_invoice_id` | string | Yes | Yes | Invoice the session created, if any. |
> | `provider_payment_intent_id` | string | Yes | Yes | Payment intent of the session (`payment` type); `null` for `subscription` type. |
> | `provider_setup_intent_id` | string | Yes | Yes | Setup intent of the session (`setup` type); `null` for `subscription` type. |
> | `client_reference_id` | string | Yes | Yes | Your reference for the session, if one was set. |
> | `metadata` | object | Yes | No | Free-form `string → string` session metadata; `{}` when none. |
> | `expires_at` | string | Yes | No | When the session expires. |
> | `created` | string | Yes | No | Session creation timestamp. |
> | `changed_fields` | array | Yes | No | Always `[]` on checkout session events (enum `PaymentsCheckoutSessionChangedFieldV2`). |
> | `previous` | object | No | No | Always absent on checkout session events. |

## Correlating events to your records

Events carry OpenLoop's opaque references, not your own ids. Resolve them against the synchronous
read APIs and a mapping you keep at link time:

* **Billing** — `billing_customer.provider_customer_id`, `provider_subscription_id` and
  `provider_invoice_id` on the invoice and subscription events are the same ids returned by
  `GET /v0.1/subscriptions` and `GET /v0.1/invoices`. Join on them to attach a payment event to the
  subscription or invoice you already hold. `provider_invoice_id` on a credit note event is the
  refunded invoice, `provider_payment_intent_id` on a dispute event leads to the disputed payment,
  and `provider_checkout_session_id` on a checkout session event is the id
  `POST /v0.1/checkouts/sessions` returned.
* **Your patient id** — `emr_patient_id`, when an event carries it, is the patient's `/v0.1` id, the
  `id` that `GET /v0.1/patients/{id}` takes. Prescription, patient-document, intake, charting and
  requested-form-completion events carry it, as does the `1.0` clinical appointment event, whenever
  the producer knows the id; it is omitted otherwise and never `null`. When it is present, key the
  event to the patient by it. When it is absent, fall back to the keys below.
* **Patients and orders** — `patient_ref` is an opaque surrogate, not your patient id. Map it to your
  record once when the patient is linked and store the mapping; see
  [Order status and tracking](https://openloop.mintlify.site/cookbook/order-status-and-tracking.md).
* **Labs** — `resource_id` on `lab_order.*` and `lab_order_ref` on `lab_result.*` are the
  `order_id` that `POST /v0.1/laboratories` returned. Store it when you place the order and key both
  families on it. This only helps once your lab network account is linked to your organization:
  until then no lab event is delivered to you. `patient_ref` on lab events is always `null` today.
* **Intake and charting** — `encounter_id` on `intake.*` and `charting.*` is the Partner API
  encounter id, the same value your completed submit returned, so key those events by it.
  `patient_ref` on them is not guaranteed to be your `/v0.1` patient id. Do not assume it is.
* **Form requests** — `intake_id` on `requested_form_completion.*` is the `resource_id` of the
  requested form's `intake.*` (at `1.0`) or `charting.*` events, and both carry the same
  `questionnaire_ref`; join the request to the form by it.
* **Prescriptions** — `charting_note_id` on `prescription.*` is the charting note the prescription
  was ordered from: the `resource_id` of that note's `charting.*` events. Key prescriptions to the
  note by it; it is omitted when the prescription was not ordered from a charting note.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.