Delete Billing Profile Payer¶

Removes a payer from a billing profile.

Endpoint¶

DELETE /v2/billing-profiles/{billing_profile_id}/payers/{payer_id}

Path Parameters¶

Parameter	Type	Required	Description
`billing_profile_id`	string	Yes	The billing profile this record belongs to.
`payer_id`	string	Yes	This payer row's own `id` (from List Billing Profile Payers), not the payer registry id.

Headers¶

Header	Required	Description
`If-Match`	Yes	`ETag` from a prior read, or `*`. A missing value returns `428`; a stale one `412`.

Request¶

curl --location '{base_url}/v2/billing-profiles/b7e4c1a2-6f3d-4e9b-9a51-2c8d0f7e3a14/payers/9f1c8a2e-4b31-4d0a-9c77-2f5ab8e10c44' \
  --request DELETE \
  --header 'Authorization: Bearer JWT_TOKEN' \
  --header 'If-Match: "<etag>"'

Response¶

Success Response¶

Code: 204 No Content

No response body.

Error Response¶

Code: 400 Bad Request

{
  "code": "bad_request",
  "message": "Validation failed",
  "errors": [
    {
      "field": "patient_id",
      "message": "must be a string"
    }
  ]
}

Every error has the same shape — a machine-readable code, a message, and an errors[] array that's empty when there's nothing field-specific to report. The HTTP status is authoritative.

Status	`code`	Meaning
`400 Bad Request`	`bad_request`	The request body or parameters failed validation. `errors[]` names the offending fields.
`401 Unauthorized`	`unauthorized`	The access token is missing, malformed or expired.
`403 Forbidden`	`forbidden`	The request references a resource outside the token's organisation or clinic scope.
`404 Not Found`	`not_found`	No such resource, or it's outside your scope.
`409 Conflict`	`conflict`	The record conflicts with existing state — see the endpoint's notes.
`412 Precondition Failed`	`precondition_failed`	`If-Match` is stale. Re-read the resource and retry.
`423 Locked`	`locked`	The organisation has a publish in progress. Retry once it finishes.
`428 Precondition Required`	`precondition_required`	`If-Match` is required on this write.
`429 Too Many Requests`	`rate_limited`	Rate limit exceeded. Back off and retry.
`500 Internal Server Error`	`internal_error`	Unexpected server error.
`502 Bad Gateway`	`upstream_error`	Upstream service failed or timed out.

Notes¶

The payer_id path parameter is this row's own id, not the payer registry id.
The payer's credentialing rows on this profile are removed with it, except history rows (below).
History rows: on a billing-profiles organisation a published credentialing row covering dates of service before the clinic-local today isn't removed by a delete, a payer detach, an overwrite payer import or a provider delete. It is ended and stays listed as history, so billing keeps it for visits up to its end: a row with no end date, or one ending after today, gets effective_to = today; a row whose effective_to had already passed keeps its own. A row without past coverage is removed. Moving a history row's effective_to past today, or clearing it, with Update Credentialing Row re-opens it (refused with 400 PROVIDER_UNKNOWN on provider_id, from cosigner.provider_id, while its co-signer is a deleted provider: pick another co-signer or send cosigner: null too). Only a create of the same row — Create or Bulk Create — is refused with 409 CRED_ROW_ENDED.
A detached payer's history rows list without payer_id (the profile no longer has a payer row for them); payer_name still names the payer. They are read-only (400 CRED_ROW_READ_ONLY on an update or claim hold) until the payer is attached to this profile again, which links them back to the new payer row so they can be re-opened. A history row of a deleted provider stays read-only for good. A plan override's history row whose plan had its own payer row when it ended stays read-only while that plan's payer row is gone.
When onboarding refuses a write, each errors[] entry carries a code naming the rule that failed, and field names the field in snake_case, as this API spells it (an empty field means the whole row, or the whole create, not one field).