Skip to main content
POST
Record a payment or adjustment

Authorizations

​
X-API-Key
string
header
required

Public API key: cxp_<hex> (firm-scoped) or cxpp_<hex> (provider-scoped). Required on every request.

Path Parameters

​
caseId
string<uuid>
required

Med case UUID: medCaseId in the referral.* webhook payload, or the id from GET /med-cases.

​
referralId
string<uuid>
required

Med referral UUID: the referral of this case to your pharmacy practice. Find it with GET /med-cases/{id}/referrals, or take it from the referral.* webhook payload.

Body

application/json
​
type
enum<string>
required

ADJUSTMENT and WRITE_OFF count under adjustments; PAYMENT and REFUND count under paid; a REVERSAL counts under the bucket of the transaction it reverses. A REVERSAL with no reversesTransactionId, or whose target is not in the ledger, counts under paid. Sign convention: a positive amount reduces the balance, a negative amount increases it. The API stores the amount exactly as sent and does not check the sign against the type, so post the sign you mean. Examples: a payment received is PAYMENT "40.00"; a payer taking a payment back is PAYMENT "-40.00" or REVERSAL "-40.00"; a contractual write-down is ADJUSTMENT "15.00"; a write-off is WRITE_OFF with a positive amount; a refund the pharmacy sends out is REFUND "-10.00" (REFUND "10.00" would reduce the balance).

Available options:
PAYMENT,
ADJUSTMENT,
WRITE_OFF,
REFUND,
REVERSAL
​
amount
string
required

Sign convention: a positive amount reduces the balance, a negative amount increases it. The API stores the amount exactly as sent and does not check the sign against the type, so post the sign you mean. Examples: a payment received is PAYMENT "40.00"; a payer taking a payment back is PAYMENT "-40.00" or REVERSAL "-40.00"; a contractual write-down is ADJUSTMENT "15.00"; a write-off is WRITE_OFF with a positive amount; a refund the pharmacy sends out is REFUND "-10.00" (REFUND "10.00" would reduce the balance).

Pattern: ^-?\d{1,10}(\.\d{1,2})?$
​
transactionDate
string<date>
required

YYYY-MM-DD, a real calendar date.

​
externalId
string

Your system's id for this record (e.g. a PioneerRx event id). Unique per practice within each resource type (fills, transactions and snapshots each have their own namespace), across all of the practice's referrals and cases: it is not scoped to a referral, so do not reuse one id for two referrals. Re-sending the same externalId with the same payload returns the existing record (200, meta.replayed=true), even after the referral has moved to a status that no longer accepts new records; with a different payload, 409 external_id_conflict. A replay is compared with the record as it is now, so re-sending the original POST after any PATCH to that record returns 409 external_id_conflict; to recover, PATCH the record at error.details.existingId instead of re-posting. Referenced ids (prescriptionId, claimDocumentId, fillId, reversesTransactionId) are part of the compared payload, so a replay after the referenced record was deleted (its link cleared) also returns 409 external_id_conflict. Leading and trailing whitespace is trimmed. A POST without an externalId is accepted but never deduplicated, so always send one.

Required string length: 1 - 200
​
fillId
string<uuid> | null

A fill on this referral; otherwise 400 invalid_reference.

​
payer
string | null
Maximum string length: 300
​
reference
string | null
Maximum string length: 200
​
reversesTransactionId
string<uuid> | null

Allowed only when type is REVERSAL (otherwise 400 validation_error). Must be a transaction on this referral (otherwise 400 invalid_reference).

​
note
string | null
Maximum string length: 2000

Response

Replay: the externalId was already used with the same payload. The existing transaction is returned, nothing is written, logged or emitted, and meta.replayed is true.

​
data
object
required

A payment, adjustment, write-off, refund or reversal against the pharmacy's billing. Immutable once recorded except payer, reference, note and fillId: to correct an amount, post a REVERSAL.

​
meta
object
required