# Bills

AP bill management operations.
Bills represent carrier and vendor invoices to be paid.


## Filter bills

 - [POST /bills/filter](https://docs.mvmnt.io/apis/openapi/bills/filterbills.md): Search for AP bills using filter criteria.

## Common Filters

- By carrier: { "filter": { "carrierId": { "equalTo": "uuid" } } }
- By vendor: { "filter": { "vendorId": { "equalTo": "uuid" } } }
- Awaiting approval: { "filter": { "status": { "equalTo": "IN_REVIEW" } } }
- By shipment: { "filter": { "shipmentId": { "equalTo": "uuid" } } }
- Overdue: { "filter": { "overdue": true } }

## Record a bill

 - [POST /bills](https://docs.mvmnt.io/apis/openapi/bills/createbill.md): Record a carrier or vendor bill (invoice).

## What happens

- Bill record is created for the load carrier or vended service
- Entity status updates to IN_REVIEW
- Due date calculated from payment term if not provided

## Prerequisites

- LoadCarrier or VendedService must exist
- Entity must be in AWAITING_INVOICE status

## Get a bill

 - [GET /bills/{id}](https://docs.mvmnt.io/apis/openapi/bills/getbill.md): Retrieve a bill by ID.

The response includes payments applied and carrier/vendor details.

## Update a bill

 - [PATCH /bills/{id}](https://docs.mvmnt.io/apis/openapi/bills/updatebill.md): Update bill fields.

## Constraints

- Cannot change amount if payments have been applied
- Status changes use action endpoints

## Delete a bill

 - [DELETE /bills/{id}](https://docs.mvmnt.io/apis/openapi/bills/deletebill.md): Delete a bill.

## Prerequisites

- Bill must not have any payments applied

## What happens

- Bill record is deleted
- Entity status reverts to AWAITING_INVOICE

## Approve bill for payment

 - [POST /bills/{id}/approve](https://docs.mvmnt.io/apis/openapi/bills/approvebill.md): Approve a bill for payment.

## What happens

- Bill status changes to APPROVED_TO_PAY
- Bill is now ready for payment

## Prerequisites

- Bill must be in IN_REVIEW status

## Batch approve bills

 - [POST /bills/batch-approve](https://docs.mvmnt.io/apis/openapi/bills/batchapprovebills.md): Approve multiple bills for payment in a single request.

Bills that cannot be approved will be returned in the failed array.

## Unapprove bill

 - [POST /bills/{id}/unapprove](https://docs.mvmnt.io/apis/openapi/bills/unapprovebill.md): Revert bill from approved back to in review.

## What happens

- Bill status changes to IN_REVIEW

## Prerequisites

- Bill must be in APPROVED_TO_PAY status
- Bill must not have any payments

## Revert bill to awaiting invoice

 - [POST /bills/{id}/revert](https://docs.mvmnt.io/apis/openapi/bills/revertbill.md): Revert bill completely back to awaiting invoice state.

## What happens

- Bill record is deleted
- Any payments are deleted
- Entity status reverts to AWAITING_INVOICE

## Use case

Use when a bill was recorded incorrectly and needs to start over.

## Get bill payments

 - [GET /bills/{id}/payments](https://docs.mvmnt.io/apis/openapi/bills/getbillpayments.md): List all payments applied to a specific bill.

## Get AP aging report

 - [GET /bills/aging-report](https://docs.mvmnt.io/apis/openapi/bills/getapagingreport.md): Generate accounts payable aging report.

## Report buckets

By default: Current, 1-30, 31-60, 61-90, 90+ days

## Export formats

- JSON (default)
- CSV (set Accept header to text/csv)