> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.taigabilling.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.taigabilling.com/_mcp/server.

# Create a price

POST https://api.taigabilling.com/api/prices/v1
Content-Type: application/json

Prices a visit's patient responsibility before it happens. Pricing must be enabled for the credential's organization in the target environment. Answers 200 with the finished price, or 202 while it is still processing; use [price readback](/api-reference/prices/get-price) to check its status.

For staging, send the sandbox example below to `https://api-staging.taigabilling.com` with a staging API key and a `billing_provider_npi` in its scope. Use sandbox payer `SBX01` and member `SBX-ACTIVE` for an active-coverage test; find supported payer identifiers with [payer lookup](/api-reference/prices/list-price-payers). A sandbox price has `livemode: false`.

Reference: https://docs.taigabilling.com/api-reference/prices/create-price

## Authentication

- `Authorization` header (bearer token, required) — Send your Taiga API key as a Bearer token. Create and manage keys in the Taiga developer portal.

## Servers

- `https://api.taigabilling.com` (Production, default)
- `https://api-staging.taigabilling.com` (Staging)

## Request

### Headers

- `Idempotency-Key` (string, required) — Retrying with the same key and body returns the same result.

### Body (application/json)

This endpoint expects a PriceCreate.

- `billing_provider_npi` (string, required)
- `insurances` (list of PriceCreateInsurancesItems, required) — Primary first, then an optional secondary.
- `patient` (PriceCreatePatient, required)
- `provider` (PriceCreateProvider, required)
- `appointment` (PriceCreateAppointment, optional)
- `items` (list of PriceCreateItemsItems, optional)
- `service_date` (date, optional)
- `treatments` (PriceCreateTreatments, optional)

## Response

### 200

Price

- `created_at` (datetime, required)
- `id` (string, required)
- `livemode` (boolean, required) — `false` for test prices built from synthetic data.
- `mode` (enum, required)
  - Allowed values: `codes_provided`, `treatment_selection`
- `object` (enum, required)
  - Allowed values: `price`
- `status` (enum, required)
  - Allowed values: `processing`, `completed`, `failed`
- `add_ons` (list of PriceAddOnsItems, optional, nullable) — Codes that may be billed in addition to the base visit.
- `alternatives` (list of PriceAlternativesItems, optional, nullable) — Codes that may be billed instead of a base line.
- `base` (PriceBase, optional, nullable) — The expected visit, present once the price completes.
- `disclosure` (string, optional, nullable) — Text that must be shown to the patient verbatim.
- `error` (PriceError, optional) — Present only when `status` is `failed`.
- `insurances` (list of PriceInsurancesItems, optional, nullable) — Coverage verification outcome, in request order.
- `references` (PriceReferences, optional)
- `service_date` (date, optional, nullable)
- `totals` (PriceTotals, optional, nullable)

### 202

Price still processing

- `created_at` (datetime, required)
- `id` (string, required)
- `livemode` (boolean, required) — `false` for test prices built from synthetic data.
- `mode` (enum, required)
  - Allowed values: `codes_provided`, `treatment_selection`
- `object` (enum, required)
  - Allowed values: `price`
- `status` (enum, required)
  - Allowed values: `processing`, `completed`, `failed`
- `add_ons` (list of PriceAddOnsItems, optional, nullable) — Codes that may be billed in addition to the base visit.
- `alternatives` (list of PriceAlternativesItems, optional, nullable) — Codes that may be billed instead of a base line.
- `base` (PriceBase, optional, nullable) — The expected visit, present once the price completes.
- `disclosure` (string, optional, nullable) — Text that must be shown to the patient verbatim.
- `error` (PriceError, optional) — Present only when `status` is `failed`.
- `insurances` (list of PriceInsurancesItems, optional, nullable) — Coverage verification outcome, in request order.
- `references` (PriceReferences, optional)
- `service_date` (date, optional, nullable)
- `totals` (PriceTotals, optional, nullable)

## Errors

### 400 Bad Request Error

The request could not be completed.

- `message` (string, required)
- `error` (ApiPricesV1PostResponsesContentApplicationJsonSchemaError, optional)

### 401 Unauthorized Error

The request could not be completed.

- `message` (string, required)
- `error` (ApiPricesV1PostResponsesContentApplicationJsonSchemaError, optional)

### 403 Forbidden Error

The request could not be completed.

- `message` (string, required)
- `error` (ApiPricesV1PostResponsesContentApplicationJsonSchemaError, optional)

### 404 Not Found Error

The request could not be completed.

- `message` (string, required)
- `error` (ApiPricesV1PostResponsesContentApplicationJsonSchemaError, optional)

### 409 Conflict Error

The request could not be completed.

- `message` (string, required)
- `error` (ApiPricesV1PostResponsesContentApplicationJsonSchemaError, optional)

### 429 Too Many Requests Error

The request could not be completed.

- `message` (string, required)
- `error` (ApiPricesV1PostResponsesContentApplicationJsonSchemaError, optional)

### 502 Bad Gateway Error

The request could not be completed.

- `message` (string, required)
- `error` (ApiPricesV1PostResponsesContentApplicationJsonSchemaError, optional)

## Types

### PriceCreateInsurancesItems

- `member_id` (string, required)
- `payer_id` (string, required) — Payer id or exact payer name.
- `state` (string, required) — Two-letter US state of the plan.
- `group_number` (string, optional)
- `plan_name` (string, optional)

### PriceCreatePatient

- `dob` (date, required)
- `first_name` (string, required)
- `last_name` (string, required)
- `reference` (string, optional) — Your patient id. Required with `appointment`.

### PriceCreateProvider

- `last_name` (string, required)
- `npi` (string, required)

### PriceCreateAppointment

- `type` (string, required) — Appointment type as scheduled.
- `department` (string, optional)
- `location` (string, optional)
- `notes` (string, optional)
- `reference` (string, optional)
- `scheduled_for` (datetime, optional)
- `specialty` (string, optional)

### PriceCreateItemsItems

- `code` (string, required)
- `modifiers` (list of string, optional, default: [])

### PriceCreateTreatments

- `trt_id` (string, required) — A prediction id from the treatments endpoint.

### PriceAddOnsItems

- `adjustments` (list of PriceAddOnsItemsAdjustmentsItems, optional)
- `allowed` (integer, optional, nullable) — Payer-allowed amount for this line, in cents.
- `code` (string, optional)
- `id` (string, optional)
- `modifiers` (list of string, optional, default: [])
- `patient_responsibility` (integer, optional, nullable) — Patient responsibility for this line, in cents.
- `pricing_basis` (string, optional) — `insured` when priced against the patient's benefits; `cash_fallback` when coverage was inactive or out of network and the practice's cash price applies.
- `probability` (double, optional, nullable) — Likelihood the predicted code is billed, when the code was predicted from the appointment.
- `status` (string, optional) — `priced`, or why the line could not be priced: `unmapped_code` or `insufficient_data`.
- `treatment` (PriceAddOnsItemsTreatment, optional, nullable)

### PriceAlternativesItems

- `adjustments` (list of PriceAlternativesItemsAdjustmentsItems, optional)
- `allowed` (integer, optional, nullable) — Payer-allowed amount for this line, in cents.
- `code` (string, optional)
- `id` (string, optional)
- `modifiers` (list of string, optional, default: [])
- `patient_responsibility` (integer, optional, nullable) — Patient responsibility for this line, in cents.
- `pricing_basis` (string, optional) — `insured` when priced against the patient's benefits; `cash_fallback` when coverage was inactive or out of network and the practice's cash price applies.
- `probability` (double, optional, nullable) — Likelihood the predicted code is billed, when the code was predicted from the appointment.
- `status` (string, optional) — `priced`, or why the line could not be priced: `unmapped_code` or `insufficient_data`.
- `treatment` (PriceAlternativesItemsTreatment, optional, nullable)

### PriceBase

The expected visit, present once the price completes.

- `items` (list of PriceBaseItemsItems, optional)

### PriceError

Present only when `status` is `failed`.

- `code` (string, optional)
- `message` (string, optional)
- `type` (string, optional)

### PriceInsurancesItems

- `accumulators` (PriceInsurancesItemsAccumulators, optional, nullable)
- `network` (string, optional, nullable)
- `payer_id` (string, optional)
- `priority` (enum, optional)
  - Allowed values: `primary`, `secondary`
- `status` (string, optional)

### PriceReferences

- `appointment` (string, optional, nullable)
- `patient` (string, optional, nullable)

### PriceTotals

- `base` (integer, optional, nullable) — Patient responsibility for the priced base lines, in cents. Null when no line could be priced.
- `base_plus_add_ons_max` (integer, optional, nullable) — Upper bound of the base plus every add-on, in cents.
- `priced_items` (integer, optional)
- `unpriced_items` (integer, optional)

### ApiPricesV1PostResponsesContentApplicationJsonSchemaError

- `candidates` (list of string, optional) — Matching payer ids when `payer_id` was ambiguous.
- `code` (string, optional)
- `message` (string, optional)
- `param` (string, optional) — The request field at fault.
- `retryable` (boolean, optional) — Retry unchanged only when true.
- `type` (string, optional)

### PriceAddOnsItemsAdjustmentsItems

- `amount` (integer, optional) — Cents.
- `type` (enum, optional)
  - Allowed values: `copay`, `deductible`, `coinsurance`

### PriceAddOnsItemsTreatment

- `name` (string, optional)

### PriceAlternativesItemsAdjustmentsItems

- `amount` (integer, optional) — Cents.
- `type` (enum, optional)
  - Allowed values: `copay`, `deductible`, `coinsurance`

### PriceAlternativesItemsTreatment

- `name` (string, optional)

### PriceBaseItemsItems

- `adjustments` (list of PriceBaseItemsItemsAdjustmentsItems, optional)
- `allowed` (integer, optional, nullable) — Payer-allowed amount for this line, in cents.
- `code` (string, optional)
- `id` (string, optional)
- `modifiers` (list of string, optional, default: [])
- `patient_responsibility` (integer, optional, nullable) — Patient responsibility for this line, in cents.
- `pricing_basis` (string, optional) — `insured` when priced against the patient's benefits; `cash_fallback` when coverage was inactive or out of network and the practice's cash price applies.
- `probability` (double, optional, nullable) — Likelihood the predicted code is billed, when the code was predicted from the appointment.
- `status` (string, optional) — `priced`, or why the line could not be priced: `unmapped_code` or `insufficient_data`.
- `treatment` (PriceBaseItemsItemsTreatment, optional, nullable)

### PriceInsurancesItemsAccumulators

- `deductible_remaining` (integer, optional, nullable) — Cents.
- `oop_max_remaining` (integer, optional, nullable) — Cents.
- `plan_deductible` (integer, optional, nullable) — Cents.
- `plan_oop_max` (integer, optional, nullable) — Cents.

### PriceBaseItemsItemsAdjustmentsItems

- `amount` (integer, optional) — Cents.
- `type` (enum, optional)
  - Allowed values: `copay`, `deductible`, `coinsurance`

### PriceBaseItemsItemsTreatment

- `name` (string, optional)

## Examples

### Insured visit

**Request**

```json
{
  "billing_provider_npi": "1669095808",
  "insurances": [
    {
      "member_id": "W123456789",
      "payer_id": "60054",
      "state": "NY"
    }
  ],
  "patient": {
    "dob": "1984-04-04",
    "first_name": "Jane",
    "last_name": "Doe",
    "reference": "patient-001"
  },
  "provider": {
    "last_name": "Smith",
    "npi": "1234567893"
  },
  "items": [
    {
      "code": "99213",
      "modifiers": []
    },
    {
      "code": "80053",
      "modifiers": []
    }
  ]
}
```

**Response**

```json
{
  "created_at": "2024-01-15T09:30:00Z",
  "id": "string",
  "livemode": true,
  "mode": "codes_provided",
  "object": "price",
  "status": "processing",
  "add_ons": [
    {
      "adjustments": [
        {
          "amount": 1,
          "type": "copay"
        }
      ],
      "allowed": 1,
      "code": "string",
      "id": "string",
      "modifiers": [
        "string"
      ],
      "patient_responsibility": 1,
      "pricing_basis": "string",
      "probability": 1.1,
      "status": "string",
      "treatment": {
        "name": "string"
      }
    }
  ],
  "alternatives": [
    {
      "adjustments": [
        {
          "amount": 1,
          "type": "copay"
        }
      ],
      "allowed": 1,
      "code": "string",
      "id": "string",
      "modifiers": [
        "string"
      ],
      "patient_responsibility": 1,
      "pricing_basis": "string",
      "probability": 1.1,
      "status": "string",
      "treatment": {
        "name": "string"
      }
    }
  ],
  "base": {
    "items": [
      {
        "adjustments": [
          {
            "amount": 1,
            "type": "copay"
          }
        ],
        "allowed": 1,
        "code": "string",
        "id": "string",
        "modifiers": [
          "string"
        ],
        "patient_responsibility": 1,
        "pricing_basis": "string",
        "probability": 1.1,
        "status": "string",
        "treatment": {
          "name": "string"
        }
      }
    ]
  },
  "disclosure": "string",
  "error": {
    "code": "string",
    "message": "string",
    "type": "string"
  },
  "insurances": [
    {
      "accumulators": {
        "deductible_remaining": 1,
        "oop_max_remaining": 1,
        "plan_deductible": 1,
        "plan_oop_max": 1
      },
      "network": "string",
      "payer_id": "string",
      "priority": "primary",
      "status": "string"
    }
  ],
  "references": {
    "appointment": "string",
    "patient": "string"
  },
  "service_date": "2023-01-15",
  "totals": {
    "base": 1,
    "base_plus_add_ons_max": 1,
    "priced_items": 1,
    "unpriced_items": 1
  }
}
```

**SDK Code**

```python Insured visit
import requests

url = "https://api.taigabilling.com/api/prices/v1"

payload = {
    "billing_provider_npi": "1669095808",
    "insurances": [
        {
            "member_id": "W123456789",
            "payer_id": "60054",
            "state": "NY"
        }
    ],
    "patient": {
        "dob": "1984-04-04",
        "first_name": "Jane",
        "last_name": "Doe",
        "reference": "patient-001"
    },
    "provider": {
        "last_name": "Smith",
        "npi": "1234567893"
    },
    "items": [
        {
            "code": "99213",
            "modifiers": []
        },
        {
            "code": "80053",
            "modifiers": []
        }
    ]
}
headers = {
    "Idempotency-Key": "Idempotency-Key",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

### Insured visit

**Request**

```json
{
  "billing_provider_npi": "1669095808",
  "insurances": [
    {
      "member_id": "W123456789",
      "payer_id": "60054",
      "state": "NY"
    }
  ],
  "patient": {
    "dob": "1984-04-04",
    "first_name": "Jane",
    "last_name": "Doe",
    "reference": "patient-001"
  },
  "provider": {
    "last_name": "Smith",
    "npi": "1234567893"
  },
  "items": [
    {
      "code": "99213",
      "modifiers": []
    },
    {
      "code": "80053",
      "modifiers": []
    }
  ]
}
```

**Response**

```json
{
  "created_at": "2024-01-15T09:30:00Z",
  "id": "string",
  "livemode": true,
  "mode": "codes_provided",
  "object": "price",
  "status": "processing",
  "add_ons": [
    {
      "adjustments": [
        {
          "amount": 1,
          "type": "copay"
        }
      ],
      "allowed": 1,
      "code": "string",
      "id": "string",
      "modifiers": [
        "string"
      ],
      "patient_responsibility": 1,
      "pricing_basis": "string",
      "probability": 1.1,
      "status": "string",
      "treatment": {
        "name": "string"
      }
    }
  ],
  "alternatives": [
    {
      "adjustments": [
        {
          "amount": 1,
          "type": "copay"
        }
      ],
      "allowed": 1,
      "code": "string",
      "id": "string",
      "modifiers": [
        "string"
      ],
      "patient_responsibility": 1,
      "pricing_basis": "string",
      "probability": 1.1,
      "status": "string",
      "treatment": {
        "name": "string"
      }
    }
  ],
  "base": {
    "items": [
      {
        "adjustments": [
          {
            "amount": 1,
            "type": "copay"
          }
        ],
        "allowed": 1,
        "code": "string",
        "id": "string",
        "modifiers": [
          "string"
        ],
        "patient_responsibility": 1,
        "pricing_basis": "string",
        "probability": 1.1,
        "status": "string",
        "treatment": {
          "name": "string"
        }
      }
    ]
  },
  "disclosure": "string",
  "error": {
    "code": "string",
    "message": "string",
    "type": "string"
  },
  "insurances": [
    {
      "accumulators": {
        "deductible_remaining": 1,
        "oop_max_remaining": 1,
        "plan_deductible": 1,
        "plan_oop_max": 1
      },
      "network": "string",
      "payer_id": "string",
      "priority": "primary",
      "status": "string"
    }
  ],
  "references": {
    "appointment": "string",
    "patient": "string"
  },
  "service_date": "2023-01-15",
  "totals": {
    "base": 1,
    "base_plus_add_ons_max": 1,
    "priced_items": 1,
    "unpriced_items": 1
  }
}
```

**SDK Code**

```python Insured visit
import requests

url = "https://api.taigabilling.com/api/prices/v1"

payload = {
    "billing_provider_npi": "1669095808",
    "insurances": [
        {
            "member_id": "W123456789",
            "payer_id": "60054",
            "state": "NY"
        }
    ],
    "patient": {
        "dob": "1984-04-04",
        "first_name": "Jane",
        "last_name": "Doe",
        "reference": "patient-001"
    },
    "provider": {
        "last_name": "Smith",
        "npi": "1234567893"
    },
    "items": [
        {
            "code": "99213",
            "modifiers": []
        },
        {
            "code": "80053",
            "modifiers": []
        }
    ]
}
headers = {
    "Idempotency-Key": "Idempotency-Key",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

### Staging sandbox

**Request**

```json
{
  "billing_provider_npi": "1669095808",
  "insurances": [
    {
      "member_id": "SBX-ACTIVE",
      "payer_id": "SBX01",
      "state": "NY"
    }
  ],
  "patient": {
    "dob": "1984-04-04",
    "first_name": "Jane",
    "last_name": "Doe",
    "reference": "patient-001"
  },
  "provider": {
    "last_name": "Smith",
    "npi": "1234567893"
  },
  "items": [
    {
      "code": "99213",
      "modifiers": []
    },
    {
      "code": "80053",
      "modifiers": []
    }
  ]
}
```

**Response**

```json
{
  "created_at": "2024-01-15T09:30:00Z",
  "id": "string",
  "livemode": true,
  "mode": "codes_provided",
  "object": "price",
  "status": "processing",
  "add_ons": [
    {
      "adjustments": [
        {
          "amount": 1,
          "type": "copay"
        }
      ],
      "allowed": 1,
      "code": "string",
      "id": "string",
      "modifiers": [
        "string"
      ],
      "patient_responsibility": 1,
      "pricing_basis": "string",
      "probability": 1.1,
      "status": "string",
      "treatment": {
        "name": "string"
      }
    }
  ],
  "alternatives": [
    {
      "adjustments": [
        {
          "amount": 1,
          "type": "copay"
        }
      ],
      "allowed": 1,
      "code": "string",
      "id": "string",
      "modifiers": [
        "string"
      ],
      "patient_responsibility": 1,
      "pricing_basis": "string",
      "probability": 1.1,
      "status": "string",
      "treatment": {
        "name": "string"
      }
    }
  ],
  "base": {
    "items": [
      {
        "adjustments": [
          {
            "amount": 1,
            "type": "copay"
          }
        ],
        "allowed": 1,
        "code": "string",
        "id": "string",
        "modifiers": [
          "string"
        ],
        "patient_responsibility": 1,
        "pricing_basis": "string",
        "probability": 1.1,
        "status": "string",
        "treatment": {
          "name": "string"
        }
      }
    ]
  },
  "disclosure": "string",
  "error": {
    "code": "string",
    "message": "string",
    "type": "string"
  },
  "insurances": [
    {
      "accumulators": {
        "deductible_remaining": 1,
        "oop_max_remaining": 1,
        "plan_deductible": 1,
        "plan_oop_max": 1
      },
      "network": "string",
      "payer_id": "string",
      "priority": "primary",
      "status": "string"
    }
  ],
  "references": {
    "appointment": "string",
    "patient": "string"
  },
  "service_date": "2023-01-15",
  "totals": {
    "base": 1,
    "base_plus_add_ons_max": 1,
    "priced_items": 1,
    "unpriced_items": 1
  }
}
```

**SDK Code**

```python Staging sandbox
import requests

url = "https://api.taigabilling.com/api/prices/v1"

payload = {
    "billing_provider_npi": "1669095808",
    "insurances": [
        {
            "member_id": "SBX-ACTIVE",
            "payer_id": "SBX01",
            "state": "NY"
        }
    ],
    "patient": {
        "dob": "1984-04-04",
        "first_name": "Jane",
        "last_name": "Doe",
        "reference": "patient-001"
    },
    "provider": {
        "last_name": "Smith",
        "npi": "1234567893"
    },
    "items": [
        {
            "code": "99213",
            "modifiers": []
        },
        {
            "code": "80053",
            "modifiers": []
        }
    ]
}
headers = {
    "Idempotency-Key": "Idempotency-Key",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```