Add prescription to order

POST/v1/orders/{orderId}/prescriptions

Requires orders:write, Idempotency-Key and expectedRevision from the order being edited. Existing integrations may send expectedVersions instead; supply exactly one. Adds a complete prescription to an unsigned Order and returns all new versions. Omitted actor context defaults to the authenticated service account as a system actor. Patient and prescriber attribution stay fixed. Signed orders cannot be amended through this endpoint. Signing and submission require orders:sign through their separate endpoints.

Practices API key authenticationVersion 2026-09-28

Request example

Replace example values with your Test data. Check the field rules below before you send a request.

"<string>"

curl -X POST 'https://api.affinityrx.com/v1/orders/{orderId}/prescriptions' \
  -H "Authorization: Bearer $AFFINITY_API_KEY" \
  -H 'Affinity-Version: 2026-09-28' \
  -H 'Idempotency-Key: <Idempotency-Key>' \
  -H 'Content-Type: application/json' \
  --data @request.json

Response example

These examples show the body structure. Values can differ. Select a status code to see its response.

{
  "revision": "<string>",
  "object": "order_draft_update",
  "externalOrderId": "<string>",
  "metadata": "<string>",
  "orderId": "ord_01j2y8m6jcc9tt24af5pw9x1bc",
  "prescriptionId": "rx_01j2y8m6jcc9tt24af5pw9x1bc",
  "prescriptions": "<string>"
}

{
  "code": "<string>",
  "data": "<string>",
  "detail": "<string>",
  "instance": "<string>",
  "requestId": "<string>",
  "status": 400,
  "title": "<string>",
  "traceId": "<string>",
  "type": "<string>"
}

{
  "code": "<string>",
  "data": "<string>",
  "detail": "<string>",
  "instance": "<string>",
  "requestId": "<string>",
  "status": 401,
  "title": "<string>",
  "traceId": "<string>",
  "type": "<string>"
}

{
  "code": "<string>",
  "data": "<string>",
  "detail": "<string>",
  "instance": "<string>",
  "requestId": "<string>",
  "status": 403,
  "title": "<string>",
  "traceId": "<string>",
  "type": "<string>"
}

{
  "code": "<string>",
  "data": "<string>",
  "detail": "<string>",
  "instance": "<string>",
  "requestId": "<string>",
  "status": 404,
  "title": "<string>",
  "traceId": "<string>",
  "type": "<string>"
}

{
  "code": "<string>",
  "data": "<string>",
  "detail": "<string>",
  "instance": "<string>",
  "requestId": "<string>",
  "status": 409,
  "title": "<string>",
  "traceId": "<string>",
  "type": "<string>"
}

{
  "code": "<string>",
  "data": "<string>",
  "detail": "<string>",
  "instance": "<string>",
  "requestId": "<string>",
  "status": 422,
  "title": "<string>",
  "traceId": "<string>",
  "type": "<string>"
}

{
  "code": "<string>",
  "data": "<string>",
  "detail": "<string>",
  "instance": "<string>",
  "requestId": "<string>",
  "status": 429,
  "title": "<string>",
  "traceId": "<string>",
  "type": "<string>"
}

{
  "code": "<string>",
  "data": "<string>",
  "detail": "<string>",
  "instance": "<string>",
  "requestId": "<string>",
  "status": 503,
  "title": "<string>",
  "traceId": "<string>",
  "type": "<string>"
}

Implementation specification

Use these field types and limits to build your integration. Download the OpenAPI document for the complete contract.

Path parameters

orderIdstringrequired

Pattern: ^ord_[0-7][0-9a-hjkmnp-tv-z]{25}$

Headers

Affinity-Versionstring

Selects the HTTP API contract for this request only. When omitted, API-key requests use their service account’s stored version. Does not change the stored default.

Pin requests to 2026-09-28.

Idempotency-Keystringrequired

Affinity-Actor-Idstring

Required for user actors and optional for system actors. Omit both actor headers to use the authenticated service account as a system actor.

Affinity-Actor-Typestring

Use user when a person initiated the action and system for autonomous work. Omit both actor headers to default to system.

Request body specification application/json

metadataobject | null

Show metadata fields

Any of · 1: object

Additional properties

Any of · 1: string

string

Maximum length: 500

Pattern: ^[^\p{Cs}]*$

Any of · 2: number

number

Any of · 3: boolean

boolean

Any of · 4: null

null

object

Any of · 2: null

null

practiceIdstringrequired

Pattern: ^prac_[0-7][0-9a-hjkmnp-tv-z]{25}$

expectedRevisionstring | null

Show expectedRevision fields

Any of · 1: string

Opaque revision of the complete order prescription set. Send the revision you reviewed as expectedRevision; never replace it automatically after a conflict.

Pattern: ^rev_[a-f0-9]{64}$

Any of · 2: null

null

expectedVersionsobject[] | null

Show expectedVersions fields

Any of · 1: object[]

Array items · object

prescriptionIdstringrequired

Pattern: ^rx_[0-7][0-9a-hjkmnp-tv-z]{25}$

versionintegerrequired

Minimum: 1

Any of · 2: null

null

prescriptionobjectrequired

No additional properties

Show prescription fields

externalPrescriptionIdany | null

Show externalPrescriptionId fields

Any of · 1: any

All of · 1: any

any

Pattern: ^[^\p{Cc}\p{Cs}]*$

Any of · 2: null

null

clinicalobject | null

Show clinical fields

Any of · 1: object

compoundingReasonobject | null

Show compoundingReason fields

Any of · 1: object

categorystring | null

Show category fields

Any of · 1: string

string

Allowed: "alcohol_free", "drug_shortage", "commercial_product_discontinued", "modified_release", "inactive_ingredient_sensitivity", "inactive_ingredient_toxicity", "concentration_adjustment", "alternate_route", "dosage_form_unavailable", "flavor_adjustment", "tablet_burden", "patient_cannot_use_commercial_product", "no_approved_product_available", "no_rationale_required", "other_patient_specific_need"

Any of · 2: null

null

contextstring | null

Show context fields

Any of · 1: string

string

Any of · 2: null

null

Any of · 2: null

null

medicationReviewStatusstring | null

Show medicationReviewStatus fields

Any of · 1: string

string

Allowed: "not_reviewed", "none", "recorded"

Any of · 2: null

null

diagnosisReviewStatusstring | null

Show diagnosisReviewStatus fields

Any of · 1: string

string

Allowed: "not_reviewed", "none", "recorded"

Any of · 2: null

null

currentMedicationsstring[] | null

Show currentMedications fields

Any of · 1: string[]

Array items · string

string

Any of · 2: null

null

diagnosesobject[] | null

Show diagnoses fields

Any of · 1: object[]

Array items · object

codestringrequired

displaystringrequired

Any of · 2: null

null

observationsobject[] | null

Show observations fields

Any of · 1: object[]

Array items · object

displaystringrequired

unitstringrequired

valuenumber | stringrequired

Show value fields

Any of · 1: number

number

Greater than: 0

Any of · 2: string

string

Allowed: "Infinity", "-Infinity", "NaN"

Any of · 2: null

null

Any of · 2: null

null

pharmacyIdstring | null

Show pharmacyId fields

Any of · 1: string

string

Pattern: ^pharm_[0-7][0-9a-hjkmnp-tv-z]{25}$

Any of · 2: null

null

daysSupplyintegerrequired

Minimum: 1

Maximum: 365

dispensingobjectrequired

No additional properties

Show dispensing fields

dispenseUponAcceptanceboolean | null

Show dispenseUponAcceptance fields

Any of · 1: boolean

boolean

Any of · 2: null

null

shippingOptionIdstring | null

Show shippingOptionId fields

Any of · 1: string

string

Pattern: ^shp_[0-7][0-9a-hjkmnp-tv-z]{25}$

Any of · 2: null

null

shippingAmountCentsinteger | null

Reviewed customer shipping rate for the selected service. Preview supplies this value. Shared group rates must not be summed per prescription.

Show shippingAmountCents fields

Any of · 1: integer

integer

Minimum: 0

Any of · 2: null

null

shippingDestinationTypestring | null

Show shippingDestinationType fields

Any of · 1: string

string

Allowed: "patient"

Any of · 2: null

null

pharmacyNotesstring | null

Show pharmacyNotes fields

Any of · 1: string

string

Any of · 2: null

null

requestedFillDatestring | null

Show requestedFillDate fields

Any of · 1: string

string

Pattern: ^\d{4}-\d{2}-\d{2}$

Any of · 2: null

null

substitutionPermittedboolean | null

Show substitutionPermitted fields

Any of · 1: boolean

boolean

Any of · 2: null

null

directionsstringrequired

medicationIdstringrequired

Pattern: ^cat_[0-7][0-9a-hjkmnp-tv-z]{25}$

quantitynumber | stringrequired

Show quantity fields

Any of · 1: number

number

Maximum: 100000

Greater than: 0

Any of · 2: string

string

Allowed: "Infinity", "-Infinity", "NaN"

quantityUnitstringrequired

refillsintegerrequired

Minimum: 0

Maximum: 99

structuredSigobject | null

Show structuredSig fields

Any of · 1: object

dosestringrequired

doseUnitstringrequired

durationstring | null

Show duration fields

Any of · 1: string

string

Any of · 2: null

null

frequencystringrequired

indicationstring | null

Show indication fields

Any of · 1: string

string

Any of · 2: null

null

maxDailyUsestring | null

Show maxDailyUse fields

Any of · 1: string

string

Any of · 2: null

null

prnboolean | null

Show prn fields

Any of · 1: boolean

boolean

Any of · 2: null

null

routestringrequired

titrationSchedulestring | null

Show titrationSchedule fields

Any of · 1: string

string

Any of · 2: null

null

Any of · 2: null

null

All of · 1: any

One of · 1: any

any

One of · 2: any

any

Response specifications

200Successful response

application/json

revisionstringrequired

Opaque revision of the complete order prescription set. Send the revision you reviewed as expectedRevision; never replace it automatically after a conflict.

Pattern: ^rev_[a-f0-9]{64}$

objectstringrequired

Allowed: "order_draft_update"

externalOrderIdany | nullrequired

Show externalOrderId fields

Any of · 1: any

All of · 1: any

any

Pattern: ^[^\p{Cc}\p{Cs}]*$

Any of · 2: null

null

metadataany & anyrequired

Show metadata fields

All of · 1: any

any

All of · 2: any

any

Additional properties

Any of · 1: any & any

All of · 1: any

any

Pattern: ^[^\p{Cs}]*$

All of · 2: any

any

Maximum length: 500

Any of · 2: number

number

Any of · 3: boolean

boolean

Any of · 4: null

null

orderIdstringrequired

Pattern: ^ord_[0-7][0-9a-hjkmnp-tv-z]{25}$

prescriptionIdstringrequired

Pattern: ^rx_[0-7][0-9a-hjkmnp-tv-z]{25}$

prescriptionsany & anyrequired

Show prescriptions fields

Array items · object

idanyrequired

Show id fields

All of · 1: any

any

Pattern: ^rx_[0-7][0-9a-hjkmnp-tv-z]{25}$

externalPrescriptionIdany & any & any & any | nullrequired

Show externalPrescriptionId fields

Any of · 1: any & any & any & any

All of · 1: any

any

Minimum length: 1

All of · 2: any

any

Maximum length: 200

All of · 3: any

any

Pattern: \S

All of · 4: any

any

Pattern: ^[^\p{Cc}\p{Cs}]*$

Any of · 2: null

null

versionanyrequired

Show version fields

All of · 1: any

any

Minimum: 1

All of · 1: any

any

Minimum items: 1

All of · 2: any

any

Maximum items: 20

400HTTP 400

application/json

codestringrequired

dataobject

detailstringrequired

instancestringrequired

requestIdstringrequired

statusintegerrequired

Minimum: 400

Maximum: 599

titlestringrequired

traceIdstring

typestringrequired

Format: uri

401Unauthorized

application/json

codestringrequired

dataobject

detailstringrequired

instancestringrequired

requestIdstringrequired

statusintegerrequired

Minimum: 400

Maximum: 599

titlestringrequired

traceIdstring

typestringrequired

Format: uri

403Forbidden

application/json

codestringrequired

dataobject

detailstringrequired

instancestringrequired

requestIdstringrequired

statusintegerrequired

Minimum: 400

Maximum: 599

titlestringrequired

traceIdstring

typestringrequired

Format: uri

404Not found

application/json

codestringrequired

dataobject

detailstringrequired

instancestringrequired

requestIdstringrequired

statusintegerrequired

Minimum: 400

Maximum: 599

titlestringrequired

traceIdstring

typestringrequired

Format: uri

409Conflict

application/json

codestringrequired

dataobject

detailstringrequired

instancestringrequired

requestIdstringrequired

statusintegerrequired

Minimum: 400

Maximum: 599

titlestringrequired

traceIdstring

typestringrequired

Format: uri

422Validation error

application/json

codestringrequired

dataobject

detailstringrequired

instancestringrequired

requestIdstringrequired

statusintegerrequired

Minimum: 400

Maximum: 599

titlestringrequired

traceIdstring

typestringrequired

Format: uri

429Too many requests

application/json

codestringrequired

dataobject

detailstringrequired

instancestringrequired

requestIdstringrequired

statusintegerrequired

Minimum: 400

Maximum: 599

titlestringrequired

traceIdstring

typestringrequired

Format: uri

503HTTP 503

application/json

codestringrequired

dataobject

detailstringrequired

instancestringrequired

requestIdstringrequired

statusintegerrequired

Minimum: 400

Maximum: 599

titlestringrequired

traceIdstring

typestringrequired

Format: uri