openapi: 3.1.0 info: title: Data Exchange purchases API version: 1.0.0 servers: - url: https://api.andel.org/exchange/v1 description: Production - url: https://7403d846-765d-4d63-9e5c-b7f0ab21a354.mock.pstmn.io/exchange/v1 description: Postman mock server (sandbox; auth is not enforced) tags: - name: purchases paths: /purchases: get: operationId: listPurchases summary: List purchases description: 'List purchases visible to the authenticated tenant, ordered by `purchased_at` descending. Use cursor pagination via `since` and `limit`. ' tags: - purchases parameters: - name: member_id in: query description: Filter purchases to a single member. required: false schema: type: string - name: plan_id in: query description: Filter purchases to a single plan. Must be one of the plans the token is authorized for; otherwise the API returns `403 Forbidden`. required: false schema: type: string - name: ndc in: query description: Filter to a single NDC-11 drug code. required: false schema: type: string - name: prescriber_spi in: query description: Filter to purchases written by a specific prescriber (Surescripts SPI). required: false schema: type: string - name: event_type in: query description: Filter purchases to a single event type (e.g., only reversals). required: false schema: $ref: '#/components/schemas/PurchasesGetParametersEventType' - name: status in: query description: Filter purchases by processing status (e.g., only rejected). required: false schema: $ref: '#/components/schemas/PurchasesGetParametersStatus' - name: since in: query description: Cursor or ISO 8601 UTC timestamp. Returns purchases after this point. required: false schema: type: string - name: until in: query description: ISO 8601 UTC timestamp upper bound (exclusive). required: false schema: type: string format: date-time - name: limit in: query description: Max results per page. required: false schema: type: integer default: 100 - name: Authorization in: header description: Production machine-to-machine flow. Tokens issued by Descope. required: true schema: type: string responses: '200': description: A page of purchases. content: application/json: schema: $ref: '#/components/schemas/PurchaseList' '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Problem' '401': description: Missing or invalid token. content: application/json: schema: $ref: '#/components/schemas/Problem' '403': description: Token lacks the required scope, or is not authorized for the requested `plan_id`. content: application/json: schema: $ref: '#/components/schemas/Problem' '429': description: Too many requests. Backoff and retry. content: application/json: schema: $ref: '#/components/schemas/Problem' '500': description: Unexpected server error. content: application/json: schema: $ref: '#/components/schemas/Problem' /purchases/{purchase_id}: get: operationId: getPurchase summary: Get a single purchase tags: - purchases parameters: - name: purchase_id in: path required: true schema: type: string format: uuid - name: Authorization in: header description: Production machine-to-machine flow. Tokens issued by Descope. required: true schema: type: string responses: '200': description: A single purchase. content: application/json: schema: $ref: '#/components/schemas/Purchase' '401': description: Missing or invalid token. content: application/json: schema: $ref: '#/components/schemas/Problem' '403': description: Token lacks the required scope, or is not authorized for the requested `plan_id`. content: application/json: schema: $ref: '#/components/schemas/Problem' '404': description: Resource not found. content: application/json: schema: $ref: '#/components/schemas/Problem' '500': description: Unexpected server error. content: application/json: schema: $ref: '#/components/schemas/Problem' components: schemas: EsiIdentityTransmissionType: type: string enum: - DQ - DR description: Data Request (sent) vs Data Response (acknowledged). title: EsiIdentityTransmissionType PurchasesGetParametersEventType: type: string enum: - claim - reversal - adjustment - hra_initial_load - hra_rollover - hra_incentive title: PurchasesGetParametersEventType PurchaseNetworkInd: type: string enum: - in_network - out_of_network - both - inn_house description: Whether the fill adjudicated in- or out-of-network. title: PurchaseNetworkInd PurchaseGender: type: string enum: - unknown - male - female - non_binary description: Member gender as carried to the PBM. title: PurchaseGender PurchaseStatus: type: string enum: - accepted - rejected - pended - reversed description: Processing status of the purchase. title: PurchaseStatus PurchaseList: type: object properties: data: type: array items: $ref: '#/components/schemas/Purchase' next_cursor: type: - string - 'null' description: Pass as `since` to fetch the next page. Null when no more pages. required: - data - next_cursor title: PurchaseList EsiIdentityRequestCode: type: string enum: - '01' - '02' - '04' description: Claim / Reversal / Adjustment request code. title: EsiIdentityRequestCode Accumulator: type: object properties: type_of_benefit_account: $ref: '#/components/schemas/AccumulatorTypeOfBenefitAccount' description: Which benefit accumulator this delta applies to. participation_type: $ref: '#/components/schemas/AccumulatorParticipationType' description: Network level this accumulator tracks (may differ per accumulator). amount: type: number format: double description: (Proposed - provenance pending) Dollars applied to this accumulator on this purchase, USD. cr_db_indicator: $ref: '#/components/schemas/AccumulatorCrDbIndicator' description: '`debit` consumes the accumulator, `credit` restores it (a reversal), `replace` overwrites the running total, `bypass` ignores this accumulator for this transaction.' accumulated_amount: type: number format: double description: (Proposed - provenance pending) Running total applied to date, USD. Required by ESI for `replace`. remaining_amount: type: number format: double description: (Proposed - provenance pending) Amount left before the accumulator cap is met, USD. met_this_transaction: type: boolean description: True when this purchase drove `remaining_amount` to zero (e.g., deductible met on this fill). required: - type_of_benefit_account - amount - cr_db_indicator description: A per-accumulator delta applied by a purchase. A single fill can apply against up to six accumulators at once. title: Accumulator PurchasesGetParametersStatus: type: string enum: - accepted - rejected - pended - reversed title: PurchasesGetParametersStatus PurchaseProviderType: type: string enum: - ncpdp - npi - dea - copay_assist description: Qualifier describing which provider identifier is carried in the provider slot. title: PurchaseProviderType Problem: type: object properties: type: type: string format: uri title: type: string status: type: integer detail: type: string instance: type: string andel_request_id: type: string description: Pass to support to trace this request. required: - type - title - status description: RFC 9457 problem details with Andel extensions. title: Problem Purchase: type: object properties: purchase_id: type: string format: uuid description: Andel-issued unique identifier. member_id: type: string description: Plan or PBM member identifier. plan_id: type: string description: Plan that the member belongs to. Each member belongs to exactly one plan. Tokens are scoped to a set of allowed plan IDs; purchases for plans outside that set are not returned. purchased_at: type: string format: date-time description: ISO 8601 UTC timestamp from the pharmacy point-of-sale. ndc: type: string description: 11-digit National Drug Code. prescriber_spi: type: string description: Surescripts Prescriber ID. member_purchase_amount: type: number format: double description: (Proposed - provenance pending) Total amount the member paid at point-of-sale, USD. oop_amount: type: number format: double description: (Proposed - provenance pending) Member out-of-pocket portion, USD. plan_contribution: type: number format: double description: (Proposed - provenance pending) Plan's portion of the purchase (the plan contribution), USD. quantity: type: integer description: Units dispensed. currency: type: string default: USD description: ISO 4217 currency code. date_of_service: type: string format: date description: The actual fill date used for eligibility validation. Distinct from `purchased_at`, which is the point-of-sale timestamp. days_supply: type: integer description: Days of therapy the dispensed quantity covers. provider_type: $ref: '#/components/schemas/PurchaseProviderType' description: Qualifier describing which provider identifier is carried in the provider slot. pharmacy_npi: type: string description: Dispensing pharmacy identifier, when provided. network_ind: $ref: '#/components/schemas/PurchaseNetworkInd' description: Whether the fill adjudicated in- or out-of-network. event_type: $ref: '#/components/schemas/PurchaseEventType' description: The kind of accumulator event. `claim` is a normal fill; `reversal` restores accumulators for a returned or voided fill; `adjustment` is a flat or paired correction. original_purchase_id: type: - string - 'null' format: uuid description: For reversals or adjustments, the `purchase_id` of the purchase being corrected. Null for new purchases. status: $ref: '#/components/schemas/PurchaseStatus' description: Processing status of the purchase. deductible_applied: type: number format: double description: (Proposed - provenance pending) Amount of this purchase applied to the member's deductible, USD. subscriber_id: type: string description: The member's subscriber identifier at the PBM's eligibility system. Distinct from `member_id`. first_name: type: string description: Member first name. last_name: type: string description: Member last name. date_of_birth: type: string format: date description: Member date of birth. gender: $ref: '#/components/schemas/PurchaseGender' description: Member gender as carried to the PBM. relationship: $ref: '#/components/schemas/PurchaseRelationship' description: Member's relationship to the subscriber. accumulators: type: array items: $ref: '#/components/schemas/Accumulator' description: (Proposed - provenance pending) Per-accumulator deltas this purchase applies (deductible, out-of-pocket, HRA, caps). A single fill can apply against up to six accumulators at once. origin_code: $ref: '#/components/schemas/PurchaseOriginCode' description: ESI origin code for HRA balance events (`hra_initial_load`, `hra_rollover`, `hra_incentive`); `E` is a non-shared pharmacy dollars load. Omitted for pharmacy fills. plan_year: type: integer description: Plan year the balance applies to. Used for HRA balance events. esi: $ref: '#/components/schemas/EsiIdentity' required: - purchase_id - member_id - plan_id - purchased_at - currency - date_of_service - event_type title: Purchase EsiIdentity: type: object properties: sender_id: type: string description: ESI-assigned trading-partner sender identifier. receiver_id: type: string description: Receiver identifier; `MHS` when sending to ESI. signature: type: string description: 26-character composite transaction key (date + milliseconds + sequence + source-app code). claim_id: type: string description: ESI claim identifier. claim_xref_id: type: string description: Original-transaction reference on a reversal or adjustment. Mirrors `original_purchase_id`. transmission_type: $ref: '#/components/schemas/EsiIdentityTransmissionType' description: Data Request (sent) vs Data Response (acknowledged). request_code: $ref: '#/components/schemas/EsiIdentityRequestCode' description: Claim / Reversal / Adjustment request code. response_code: type: string description: ESI Data Response code; `00` is accepted, otherwise an error code. reason_code: type: string description: Granular reason detail beyond the response code. description: ESI wire-protocol identifiers, populated when a purchase is exchanged via the ESI CDH format. All fields optional. title: EsiIdentity PurchaseEventType: type: string enum: - claim - reversal - adjustment - hra_initial_load - hra_rollover - hra_incentive default: claim description: The kind of accumulator event. `claim` is a normal fill; `reversal` restores accumulators for a returned or voided fill; `adjustment` is a flat or paired correction. title: PurchaseEventType PurchaseRelationship: type: string enum: - subscriber - spouse - dependent - student - disabled_dependent - adult_dependent - domestic_partner description: Member's relationship to the subscriber. title: PurchaseRelationship AccumulatorCrDbIndicator: type: string enum: - debit - credit - replace - bypass description: '`debit` consumes the accumulator, `credit` restores it (a reversal), `replace` overwrites the running total, `bypass` ignores this accumulator for this transaction.' title: AccumulatorCrDbIndicator AccumulatorParticipationType: type: string enum: - in_network - out_of_network - combined - inn_house description: Network level this accumulator tracks (may differ per accumulator). title: AccumulatorParticipationType PurchaseOriginCode: type: string enum: - E - R description: ESI origin code for HRA balance events (`hra_initial_load`, `hra_rollover`, `hra_incentive`); `E` is a non-shared pharmacy dollars load. Omitted for pharmacy fills. title: PurchaseOriginCode AccumulatorTypeOfBenefitAccount: type: string enum: - hra - deductible - oop - cap - lifetime_cap - drug_cap - benefit_deductible - benefit_oop - base_deductible - base_oop - tmoop description: Which benefit accumulator this delta applies to. title: AccumulatorTypeOfBenefitAccount securitySchemes: andelDescopeClientCredentials: type: http scheme: bearer description: Production machine-to-machine flow. Tokens issued by Descope. andelDescopeAuthCode: type: http scheme: bearer description: Developer-exploration flow with PKCE. Used by Postman Guided Auth.