---
title: "Download Bills"
method: POST
path: "/organizations/{orgId}/bills/download/csv"
tags: ["Bill"]
---

# Download Bills

`POST /organizations/{orgId}/bills/download/csv`

## Request

- Base URL: `https://api.m3ter.com`
- URL: `https://api.m3ter.com/organizations/{orgId}/bills/download/csv`
- Auth: OAuth 2
  - Authorization code: `https://m3ter.auth.us-east-1.amazoncognito.com/oauth2/authorize`, token URL `https://m3ter.auth.us-east-1.amazoncognito.com/oauth2/token`
  - Client credentials, token URL `/oauth/token`
- TypeScript: <https://skmtc.dev/m3ter-com/apis/m3ter-api/docs/organizations/:orgId/bills/download/csv/post.ts> (a function with typed inputs; its response is checked against the schema)

Retrieve Bills data in CSV format. 

Use this endpoint for retrieving Bills data in CSV format for your Organization for a specified period. The response contains the line items for Bills in the defined time period in a comma-separated string format.

To define a time period you can use exactly one of the `startDate/endDate` or `externalInvoiceDateStart/externalInvoiceDateEnd` request parameter pairings. If you try to mix them when defining a time period - such as `startDate/externalInvoiceDateEnd` - then you'll receive an error.

You can use the `externalSystem` request parameter to control the format of the Bills data given in the comma-separated response:
- **STANDARD** A wider range of data columns is given.
- **XERO** A more limited range of data columns is given and compatible with loading into your 3rd-party Xero system.

**NOTES:** 
- **Download Limits**. You can only retrieve Bills data for a period of up to 31 days or up to a maximum of 5000 Bills. If you attempt a call that exceeds either of these two limits, you'll receive an error message
- **Empty Bills**. The CSV formatted response string is compiled by taking each of the line items found in Bills that exist in your Organization for the specified period. The Bill for each line item record is given, along with Bill Total and other billing attributes. However, if you have an *empty Bill* that exists for the specified period - one for which *no line items currently exist* - then no line item records will be shown for this Bill in the CSV formatted response.
- **Downloading a CSV File**. If you want to download a CSV file for Bills data for a specified period, use the [Download Bills URL](https://docs.m3ter.com/api/bill/download-bills-url) endpoint.

## Path parameters

- `orgId` string, required

## Request body

- DownloadCsvRequest
  - `startDate` string, date-time: Specifies the start date of the billing period for downloading Bills. Format should be a valid date in ISO 8601 format. Bills with a start date on or after this date will be included in the download.
  - `endDate` string, date-time: Specifies the end date of the billing period for downloading Bills. Format should be a valid date in ISO 8601 format. Bills with an end date on or before this date will be included in the download.
  - `externalInvoiceDateStart` string, date-time: *(Optional)*. Specifies the start date in ISO 8601 format for filtering Bills by external invoice date.
  - `externalInvoiceDateEnd` string, date-time: *(Optional)*. Specifies the end date in ISO 8601 format for filtering Bills by external invoice date.
  - `externalSystem` 'STANDARD' | 'XERO': *(Optional)*. Specifies the format of the Bills data given: - **STANDARD** A wider range of data columns is given. - **XERO** A more limited range of data columns is given and compatible with loading into your 3rd-party Xero system.

## Other responses

- `301`: Redirect to a CSV file containing the bill details
- `4XX`: Error message
- `5XX`: Error message

## Changes

- **2026-10-16** `85c514abc692`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/m3ter-com/apis/m3ter-api/changes/organizations/:orgId/bills/download/csv/post.md)

---

[API](https://skmtc.dev/m3ter-com/apis/m3ter-api.md) - [All operations](https://skmtc.dev/m3ter-com/apis/m3ter-api/llms.txt) - [OpenAPI document](https://skmtc.dev/m3ter-com/apis/m3ter-api/revisions/85c514abc692?raw)