Partner Charges

Hint is the financial home for a practice. Partners can route fees through Hint so practices receive a consolidated, all-in-one invoice and rely on consistent billing workflows. You create these as partner charges against a practice where your integration is installed.

Before you start

Billing must be enabled on your product. Service fees are a hinter-curated setting -- email [email protected] to enable billing for your product. Charging fails until it is enabled.
You must be a production-approved partner. Sandbox keys (sbx- prefix) can manage marketplace plumbing but cannot create business records like partner charges. Contact [email protected] for promotion.
Call with the practice access token, not the partner-wide key. Partner charges are created on the provider surface (/api/provider/*), which is always scoped to a specific practice. Use the practice access token you received when the practice connected (POST /api/partner/installations/connect), not your partner-wide API key.

Who pays

A partner charge is billed to either the patient or the practice, decided by whether you send a patient:

Payer	How	Result
Patient	Send `patient: { id }`.	A patient charge is created on a new customer invoice and issued.
Practice	Omit `patient`.	The fee is billed to the practice.

Line items and charge categories (below) apply to patient-billed charges only.

Creating a charge

POST to Create Partner Charge.

Field	Required	Notes
`amount_in_cents`	Yes	Total amount, in cents.
`description`	Yes	Human-readable description of the charge.
`integration_record_id`	Yes	Your own id for this charge, used for idempotency and reconciliation.
`patient`	No	`{ "id": "<patient id>" }` to bill the patient; omit to bill the practice.
`cost_in_cents`	No	Your cost, in cents. Required when your product bills on a margin fee model.
`lines`	No	Line items for an itemized charge (patient-billed only). See below.
`category`	No	Charge category for the created patient charge. See Charge categories.

{
  "partner_charge": {
    "amount_in_cents": 5000,
    "description": "Lab panel",
    "integration_record_id": "ext-12345",
    "patient": { "id": "<patient id>" },
    "category": { "type": "labs" }
  }
}

Charge categories

Every patient charge lands in a charge category. Categories are how practices organize revenue in Hint; the default set is memberships, labs, medications, vitamins_and_supplements, vaccines, imaging, supplies_and_dme, retail_items, office_visits, procedures, and fees.

Resolution, in order:

The charge's own category, if you send one.
Your product's default charge category (default_charge_category_type, set on Update Product), if configured.
Unassigned, if neither is set.

Send a category with either shape:

{ "type": "<default type>" } -- one of the default types listed above.
{ "id": "<cat-... id>" } -- any charge category on the practice, including a practice's custom categories.

Where you put it depends on the charge shape:

Single charge (no lines) -- set the top-level category on the charge.
Itemized charge (lines) -- set category on each line. The top-level category is ignored when lines are present. Lines without a category fall back to the product default.

Itemizing with line items

For an itemized charge, send lines (patient-billed only). Each line is priced and categorized independently, and the line totals must sum to amount_in_cents.

{
  "partner_charge": {
    "amount_in_cents": 10000,
    "description": "Visit + labs",
    "integration_record_id": "ext-12346",
    "patient": { "id": "<patient id>" },
    "lines": [
      { "description": "Office visit", "price_in_cents": 6000, "quantity": 1, "category": { "type": "office_visits" } },
      { "description": "Lab panel", "price_in_cents": 4000, "quantity": 1, "category": { "type": "labs" } }
    ]
  }
}

Each line also accepts a charge_item (match by Hint id, or by code + code_type) to price from the practice's charge item library. When a line uses a charge item and sends no category, the item's category applies.

Reading charges back

List Partner Charges -- all partner charges you created for the practice.
Get Partner Charge -- a single partner charge by id.