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.

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.