💡 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 |
| Total charges |
| Total expected (allowed) amount |
| Estimated insurance portion |
| Estimated patient portion |
| Estimated patient cost-share components |
| Estimated insurance adjustments |
| Total discounts |
| Total sales tax |
| 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 |
| ✅ | One entry per order item you're changing |
| ✅ | Address used for sales tax. |
|
| Order-level |
Item Fields
Field | Required | Notes |
| ✅ | From |
| ✅ |
|
| ✅ | One entry per service (HCPCS) |
|
| Patient insurance to bill for this item |
Service Fields
Field | Required | Notes |
| ✅ |
|
| ✅ |
|
| ✅ | e.g. |
| ✅ |
|
|
| If left out for a billable service, an applicable price option is chosen for you |
|
| Override amounts |
|
| Use one or the other |
|
| Percentage |
|
|
|
|
|
|
|
| Bill under a different HCPCS code |
|
| 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 |
| Invalid request, e.g. missing |
| Token missing, expired, or invalid |
| You don't have permission to access this resource |
| Order or order item not found |
| Too many requests |
