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

# API & events reference

> Every Tagada Rx endpoint and case event in one page — storefront, merchant, portal, and clinical webhooks.

# API & events reference

The compact map of the whole Rx surface. Full request/response shapes live in the [OpenAPI reference](/api-reference/introduction) and the per-SDK pages.

***

## Storefront endpoints (public — no API key)

Base: `/api/public/v1/rx`. Case routes authorize with the `(orderId, checkoutToken)` ownership proof.

| Method | Path                                | Purpose                                                    |
| ------ | ----------------------------------- | ---------------------------------------------------------- |
| `GET`  | `/required-for-product?productId=…` | Is this product Rx-gated? Returns clinical requirements    |
| `POST` | `/cases/submit`                     | Submit patient + intake after payment (PHI pass-through)   |
| `POST` | `/cases/lookup`                     | Public-safe case statuses for an order (thank-you polling) |

## Merchant endpoints (Tagada API key)

Base: `/api/v1/rx` — Node SDK namespace `tagada.rx.*`.

| Method | Path                             | Purpose                                        |
| ------ | -------------------------------- | ---------------------------------------------- |
| `GET`  | `/integration/status`            | Activation state for a store                   |
| `POST` | `/integration/activate`          | Request activation (creates pending setup fee) |
| `POST` | `/integration/confirm-setup-fee` | Flip to active once the fee is captured        |
| `GET`  | `/networks`                      | Clinical networks available to the account     |
| `GET`  | `/brand`                         | Brand clinical config (+ affiliate terms)      |
| `POST` | `/brand-clinical-config`         | Wire network credentials                       |
| `POST` | `/affiliate-terms`               | Version commission terms (account managers)    |
| `POST` | `/product-offerings`             | Map product ↔ network offering                 |
| `GET`  | `/cases`                         | List cases                                     |
| `GET`  | `/cases/{caseId}`                | Case + event timeline                          |
| `POST` | `/cases`                         | Submit a case server-side                      |
| `POST` | `/cases/{caseId}/refill`         | Manual refill trigger                          |

## Patient portal endpoints (customer CMS session)

Base: `/api/v1/rx/portal` — authenticated with the customer's `x-cms-token` (email OTP login).

| Method | Path                       | Purpose                              |
| ------ | -------------------------- | ------------------------------------ |
| `GET`  | `/cases`                   | The customer's cases                 |
| `GET`  | `/cases/{caseId}`          | One case + lifecycle timeline        |
| `GET`  | `/cases/{caseId}/messages` | Patient ↔ care-team thread (relayed) |
| `POST` | `/cases/{caseId}/messages` | Send message (text + attachments)    |
| `POST` | `/cases/{caseId}/identity` | Upload photo ID                      |

## Clinical webhooks (network → Tagada)

`POST /api/public/webhooks/rx/{networkSlug}` (e.g. `/rx/mdi`) — HMAC-SHA256 signed, processed asynchronously and idempotently. **You don't consume these**; they drive the case state you read from the APIs above.

***

## Case statuses

| Status      | Terminal?     | Rebills? |
| ----------- | ------------- | -------- |
| `requested` | no            | no       |
| `submitted` | no            | no       |
| `in_review` | no            | no       |
| `approved`  | no            | no       |
| `shipped`   | no            | **yes**  |
| `delivered` | yes (resting) | **yes**  |
| `declined`  | yes           | no       |
| `cancelled` | yes           | no       |
| `error`     | yes           | no       |

## Case events

Append-only, exposed on `GET /rx/cases/{caseId}` and the portal timeline:

| Event                           | Status after                                         |
| ------------------------------- | ---------------------------------------------------- |
| `case.requested`                | `requested`                                          |
| `case.submitted`                | `submitted`                                          |
| `case.in_review`                | `in_review`                                          |
| `case.approved`                 | `approved`                                           |
| `case.declined`                 | `declined`                                           |
| `case.cancelled`                | `cancelled`                                          |
| `case.error`                    | `error`                                              |
| `shipment.shipped`              | `shipped`                                            |
| `shipment.delivered`            | `delivered`                                          |
| `message.created`               | *(no change — portal thread + patient notification)* |
| `refill.requested`              | *(no change — rebill cycle)*                         |
| `affiliate.commission.accrued`  | *(no change — MoR ledger)*                           |
| `affiliate.commission.reversed` | *(no change — MoR ledger)*                           |

***

## Key objects at a glance

| Object           | Id prefix | Notes                                                        |
| ---------------- | --------- | ------------------------------------------------------------ |
| Rx case          | `rxcase_` | Non-PHI: statuses, network ids, amounts, timestamps          |
| Case event       | —         | Append-only timeline rows                                    |
| Product offering | —         | The product ↔ network SKU mapping (the "requires Rx" signal) |
| Affiliate terms  | —         | Versioned commission contract (MoR mode)                     |
| Integration      | —         | `provider: tagada_rx`, gated by the setup fee                |