Partner Charges

Partners can route fees through Hint by creating partner charges against a practice where their product is installed. Practice-billed charges appear on a separate invoice with the partner's name, generated alongside the practice's Hint invoice on its renewal date. Patient-billed charges follow the patient invoicing workflow described below.

For product subscription setup, pricing options, payment processing, and the portal billing workflow, start with Bill practices through Hint.

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.