Creating Charges and Invoices

Hint allows practices to define coverage plans that determine who pays for specific services (patient vs. employer vs. sponsor) and at what price. When your integration posts a charge, Hint immediately prices it, assigns it to the appropriate invoice, and returns the routing metadata so you know the next action to take.

flowchart LR
    PartnerApp[Partner app] -->|POST charge| HintCharges["/api/provider/charges"]
    HintCharges -->|Match charge item<br/>+ coverage plan| Pricing[Hint pricing engine]
    Pricing -->|Patient invoice| PatientInv[Customer invoice]
    Pricing -->|Sponsor invoice| SponsorInv[Employer invoice]
    PatientInv -->|Issue + collect| Payments[customer_invoice_payments]
    SponsorInv -->|Bill via sponsor cycle| EmployerBilling[Employer billing]
    classDef node fill:#ffffff,stroke:#dc2626,stroke-width:1px,color:#0f172a,font-size:12px
    class PartnerApp,HintCharges,Pricing,PatientInv,SponsorInv,Payments,EmployerBilling node

Charge items vs. categories

Practices configure Hint differently—some maintain a detailed library of charge items, others rely solely on categories. Align with each practice so you know whether to send explicit charge_item identifiers or just the category metadata.

• Charge items: match by Hint id or by the custom code you provide. Browse the current catalog in Admin → Charges & Taxes in your sandbox or via List Charge Items.
• Categories: when an item match is not possible, pass a category type (e.g., labs, office_visits, medication, vaccines, retail_items, fees). Accepted values are documented alongside the Create Charge endpoint.

Create a charge

POST the charge to Create Charge. Hint tries to match an existing charge item by code, applies coverage rules, and routes the line to the correct invoice. Example (no charge item ID, match by CPT code):

{
  "charge_item": {
    "name": "Initial Primary Care Visit",
    "code": "99381",
    "code_type": "CPT"
  },
  "price_in_cents": 3000,
  "quantity": 1,
  "category": {
    "type": "office_visits"
  },
  "patient": {
    "id": "pat-234lk3j24"
  }
}

Monitor the response for customer_invoice or sponsor_invoice data so you know which invoice to issue or whether Hint will include the charge in a future sponsor billing run.

How a location is assigned

Both customer invoices and individual charges carry a location. Hint resolves it with a simple precedence, plus one rule about timing that is easy to miss. Getting this right matters if you segment billed revenue by location.

Precedence when a record is created

1. A location you send is always used. Pass a location object (by id) to set it explicitly.
2. A charge with no location inherits its invoice's location. If the invoice has no location, the charge falls back to its patient's assigned location.
3. An invoice with no location you send defaults to the payer's location - the assigned location on the patient who pays the bill (the owner if you send one, otherwise the patient's linked payer, otherwise the patient).

So the reliable way to keep every line on one location is to set it on the invoice when you create it. Charges added afterward inherit it, and the patient-profile fallback never gets a chance to assign the wrong one.

Timing matters: updating an invoice's location overwrites its charges

When you change a customer invoice's location, Hint re-applies that location to every charge already on the invoice, replacing any location previously set on those charges. The most recent invoice-location update always wins. Adding a new charge afterward does not re-trigger this, so order your calls accordingly:

• To give every line the same location, set it on the invoice (or update it) - the charges follow automatically.
• To keep per-charge locations that differ from the invoice, set them on the charges after any invoice-location change, and avoid changing the invoice location afterward (it would overwrite them).

For example: create an invoice for location "Longevity", add a charge with no location (it inherits "Longevity"), then update the invoice to "Main Clinic" - the charge is now "Main Clinic", not "Longevity".

Issue invoices and collect payment

Many practices prefer to collect payment at checkout, while others let Hint handle nightly processing. Regardless of your workflow:

1. After adding all charges, issue the customer invoice referenced in the charge response.
2. Once issued, create a payment to charge the saved payment method or log an external collection.

Sponsor invoices (employer billing) follow the employer’s cadence automatically—no extra calls are needed from your integration unless you are surfacing status back to the employer.