Test mode and Live mode

Test mode and Live mode keep patient records, orders, webhook endpoints, and signing secrets separate. API keys select one mode.

Team membership, prescriber credentials, and practice locations are shared between modes for the same practice. Changes to these shared records apply in both modes.

Test mode

Use Test mode while you build and verify the integration. Platforms can sign up and begin Test integration immediately, without an invitation.

• Use only synthetic patients, providers, prescriptions, addresses, and contact data.
• Route orders only to the Affinity simulator.
• Verify retries, failures, and webhook replay before you request Live access.
• Confirm that mode-scoped resources report livemode: false.

Test mode must not contact a real pharmacy or create a real payment.

Live mode

Use Live mode only after Affinity approves the required organization access.

• Store the Live API key separately from the Test API key.
• Use current patient and provider authorization.
• Read the current catalog before you create an order.
• Treat catalog availability as time-sensitive.
• Keep controlled substances disabled.

Platform Live access requires explicit Affinity approval. An approved platform can manage Live access for practices it owns. An Affinity-issued practice invitation can also grant Live access through onboarding. Keys with orders:sign can sign and submit for an authorized clinician without an Affinity login. The integration collects signing intent. Affinity checks authority and records the exact versions.

Manage practice Live access

Your platform must have current Live approval. Use its Live API key with practices:write. Affinity checks the practice ownership link for every update. Knowing a practice ID does not grant access. Your platform cannot change another platform’s practice or an unowned practice.

Enable access during creation

For POST /v1/practices, add liveEnabled: true to the practice creation body. Include the required name, address, and practice attestations described in the API reference.

Creation records your platform as the practice owner. Platform approval alone does not automatically enable every new practice. If externalId already identifies a practice, creation returns that practice without changing its Live access. Use Update practice to change existing access.

Enable or disable existing access

Send PATCH /v1/practices/{practiceId} with liveEnabled: true to enable access or false to disable it. For example, disable access from your backend:

curl --request PATCH \
  --url "https://api.affinityrx.com/v1/practices/$AFFINITY_PRACTICE_ID" \
  --header "Authorization: Bearer $AFFINITY_LIVE_API_KEY" \
  --header "Affinity-Version: 2026-09-28" \
  --header "Content-Type: application/json" \
  --data '{"liveEnabled":false}'

Set AFFINITY_PRACTICE_ID to the public practice ID returned by the API. Omitting liveEnabled from an update preserves the current access setting.

Idempotency keys are optional for practice creation and updates. Supply one when you need safe retries of the same request.

Read liveEnabled in the response to confirm whether Live access is enabled. It is false after disablement and for Test practices. livemode identifies the resource’s mode; a Live practice can have liveEnabled: false.

Access restrictions

• Test requests cannot set liveEnabled, including false. Omit this field when creating or updating Test practices.
• A platform without current Live approval cannot enable or disable practice Live access.
• An explicit Affinity Admin Live decision takes precedence, including an approval or disablement.
• Platforms cannot change Live access for suspended or archived practices.

Denied requests return 403. An Admin-controlled practice returns practice_live_access_admin_controlled. Contact Affinity to change an Admin decision. Repeating practice creation does not override it.

Live access does not replace clinician authority checks, prescription validation, pharmacy eligibility, or billing requirements. Enabling Live access does not convert Test data into Live data.

Billing in each mode

Test mode simulates payment profiles and invoice settlement without charging a real payment method. Live orders require the payer’s billing account to meet its payment terms. For platform-managed orders, the platform is the payer, including when a provider signs in Clinic.

Configure Live billing separately. See Billing and payments for setup and blocked-order recovery.

Change modes

Change the API key and the mode configuration together. Restart the process after the change.

Run a read-only account request first. Confirm the returned mode before you permit a mutation.

Simulate pharmacy responses

Open a Test order in Clinic or Platform to use Test controls. You need permission to manage orders.

Choose a scenario before you submit the order or before pharmacy processing starts.

Automatic progression runs in background workers. Initial pharmacy acceptance can take several minutes after submission while the order is queued and simulation is initialized. Each subsequent step becomes eligible after one minute and runs when a worker next processes it; this is not a one-minute completion guarantee. Use Manual mode to request a specific response without waiting for automatic progression. Tracking numbers start with TEST- and do not identify real shipments.

Select Manual to pause progression. Use the available actions to trigger pharmacy responses. Manual actions apply to every fulfillment in the order. Each fulfillment must permit the selected action.

To test cancellation, use the normal order cancellation action first. The request remains pending until the simulator approves or declines it. In Manual mode, choose Approve cancellation or Decline cancellation in Test controls. A shipped or delivered fulfillment cannot be canceled. The simulated cutoff does not describe any real pharmacy’s cancellation policy.

API controls

Use a Test API key with orders:write. Read the controls with GET /v1/orders/{orderId}/test-simulation. Configure them with PUT /v1/orders/{orderId}/test-simulation and an Idempotency-Key header.

To hold an order before submission, send:

{
  "mode": "manual",
  "scenario": "successful"
}

After submission completes, read availableActions to find valid pharmacy responses. For example, queue acceptance with:

{
  "mode": "manual",
  "scenario": "successful",
  "action": "accept"
}

The response reports pendingAction until the worker processes the event. If the order changes before processing, lastError explains why the event could not run. Refresh the controls before you retry.

Supported actions are accept, process, ship, deliver, reject, confirm_cancellation, and decline_cancellation. Scenario values are successful, pharmacy_rejection, and cancellation_declined.

Simulation uses the normal order history and Test webhook delivery path. A pharmacy rejection produces order.blocked. Cancellation decisions produce cancellation.confirmed or cancellation.rejected. Live credentials cannot read or change Test controls.