> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pelanor.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview & Examples

> Learn how to integrate custom invoices via the API

<Card title="Custom Invoice API Example" icon="github" href="https://github.com/pelanororg/pelanor-custom-invoice-example">
  A complete, runnable script that creates a custom‑invoice integration and uploads a sample CSV file.
</Card>

**Custom Invoices** let you import cost data from vendors or services that Pelanor’s built‑in connectors don’t cover.

Once ingested, these costs appear in every dashboard, report, and alert—​alongside your cloud‑provider data. See the <a href="/integrations/services/custom-invoices">
feature documentation</a>

for more information.

### When to use the Custom Invoice API

* **Third‑party SaaS or marketplace charges** that aren’t available from native Pelanor integrations.
* **On‑prem or colocation costs** you need to view in the same place as cloud spend.
* **Ad‑hoc internal chargebacks** or any spend tracked only in spreadsheets.

<Warning>
  This API is not suitable for uploading very large datasets, such as entire cloud platform billing exports. Consult your Pelanor Solution Engineer if in doubt.
</Warning>

### Typical Flow

<Steps>
  <Step title="Create an Integration">
    Call **Create Custom Invoice Integration** once per billing account or org ID.
  </Step>

  <Step title="Prepare a CSV">
    Build a CSV with the required columns `usage_date` and `cost`.\
    Add optional columns—such as `service_name`, `region`, or `tag:{key}`—to improve filtering.
  </Step>

  <Step title="Upload the CSV">
    Use **Upload Custom Invoice File** to push the file.
  </Step>

  <Step title="Verify Ingestion">
    The file is validated server‑side; format errors are returned immediately.\
    Once accepted, data appears in Pelanor within \~12 hours.
  </Step>
</Steps>