Skip to main content

Order Cost Sharing via API (V3)

Get and save an order's cost-sharing estimate: charges, insurance and patient responsibility, copays, deductibles, discounts, and sales tax.

💡 Cost sharing is in V3. In Swagger, choose V3 Api in the Select a definition dropdown. GET /v2/orders/{id}/cost-sharing is deprecated; use the V3 endpoints below.


What is Cost Sharing?

Cost sharing breaks an order down by item and service (HCPCS) to estimate:

  • What the insurance will pay and what the patient owes

  • Copay, deductible, and coinsurance per payer

  • Discounts and sales tax

  • The total amount due from the patient

Use it to show patients their expected cost before fulfillment, or to adjust pricing on an order.


Get Cost Sharing for an Order

GET /v3/orders/{id}/cost-sharing
GET /v3/orders/SO05adce00ef4b092b90f42f97b2ec3e36/cost-sharing
{
"Items": [
{
"OrderItemId": "UN05adce00ef4b39680ac425a3882b0190",
"Qty": 1,
"BillTo": {
"Type": "Payer",
"PatientInsuranceId": "PIf5b1af006f4bdafa8b540aca26806e0d",
"PatientInsuranceName": "Example Payer",
"PatientInsuranceLevel": "Primary"
},
"Product": { "ProductId": "P31SM48ZK95CX72GA60R", "PartNumber": "464646464646", "ProductName": "Ensure Therapeutic Vanilla" },
"Services": [
{
"Hcpcs": "B4150",
"ServiceName": "Enteral formula, complete with intact nutrients",
"NonBillable": false,
"PriceOption": { "Id": "POe288ce00ef4b15e81164afd8071c128c", "Type": "Rental" },
"ChargeAmount": 250,
"PlaceOfService": { "Id": "12", "Name": "Home" },
"InsuranceEstimation": [
{ "PayerName": "Example Payer", "PayerPriority": 1, "ChargeAmount": 250, "PatientInsuranceId": "PIf5b1af006f4bdafa8b540aca26806e0d" }
]
}
],
"OrderItemTotals": {}
}
],
"OrderTotals": { "ChargeAmount": 250, "ExpectedAmount": 250 },
"SalesTaxAddress": { "AddressLine": "123 Main St", "City": "Birmingham", "State": "AL", "Zip": "35203" }
}

Order Totals

Field

Description

ChargeAmount

Total charges

ExpectedAmount

Total expected (allowed) amount

InsuranceResponsibilityAmount

Estimated insurance portion

PatientResponsibilityAmount

Estimated patient portion

CopayAmount / DeductibleAmount / CoinsuranceAmount

Estimated patient cost-share components

AdjustmentAmount

Estimated insurance adjustments

DiscountAmount

Total discounts

SalesTaxAmount

Total sales tax

DueAmount

Total amount due from the patient

Each service also includes InsuranceEstimation, a per-payer breakdown (PayerPriority 1 = primary, 2 = secondary, and so on), and ServiceItemTotals.

Amounts that don't apply may be left out of the response rather than returned as 0.


Save Cost Sharing

PUT /v3/orders/{id}/cost-sharing

Top-Level Fields

Field

Required

Notes

Items

✅

One entry per order item you're changing

SalesTaxAddress

✅

Address used for sales tax. AddressLine and City are required.

DateOfService

Order-level From / To

Item Fields

Field

Required

Notes

OrderItemId

✅

From GET /v1/orders/{orderId}/items or the cost-sharing response

ProductId

✅

Services

✅

One entry per service (HCPCS)

BillToInsuranceId

Patient insurance to bill for this item

Service Fields

Field

Required

Notes

Hcpcs

✅

ProductId

✅

PlaceOfServiceId

✅

e.g. 12

NonBillable

✅

true = no charge, tax, discount, or modifiers are applied

PriceOptionId

If left out for a billable service, an applicable price option is chosen for you

ChargeAmount / ExpectedAmount

Override amounts

DiscountRate or DiscountAmount

Use one or the other

TaxRate

Percentage

Modifiers

Mode (Replace or Append) and Level1 (both required), plus Level2–Level4

DateOfService

From / To

HcpcsSubstitution

Bill under a different HCPCS code

Note

Free text

Example: apply a 10% discount

PUT /v3/orders/SO05adce00ef4b092b90f42f97b2ec3e36/cost-sharing
{
"SalesTaxAddress": {
"AddressLine": "123 Main St",
"City": "Birmingham",
"State": "AL",
"Zip": "35203"
},
"Items": [
{
"OrderItemId": "UN05adce00ef4b39680ac425a3882b0190",
"ProductId": "P31SM48ZK95CX72GA60R",
"BillToInsuranceId": "PIf5b1af006f4bdafa8b540aca26806e0d",
"Services": [
{
"Hcpcs": "B4150",
"ProductId": "P31SM48ZK95CX72GA60R",
"PlaceOfServiceId": "12",
"NonBillable": false,
"DiscountRate": 10
}
]
}
]
}

Response: 200 OK

💡 Call GET /v3/orders/{id}/cost-sharing after saving to see the recalculated totals.


Common Errors

Code

Meaning

400

Invalid request, e.g. missing SalesTaxAddress, a missing required service field, or both DiscountRate and DiscountAmount sent

401

Token missing, expired, or invalid

403

You don't have permission to access this resource

404

Order or order item not found

429

Too many requests


Related articles

Did this answer your question?