> For the complete documentation index, see [llms.txt](https://docs.alternativepayments.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.alternativepayments.io/api-reference/bills.md).

# Bills

## List bills

> Get a paginated list of bills with optional filtering

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["accounts_payable:read"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"PaginatedResponse-BillReply":{"properties":{"data":{"items":{"$ref":"#/components/schemas/BillReply"},"type":"array"},"end_cursor":{"type":"string"},"has_next_page":{"type":"boolean"},"has_previous_page":{"type":"boolean"},"start_cursor":{"type":"string"}},"type":"object"},"BillReply":{"description":"Bill details","properties":{"amount":{"type":"number"},"created_at":{"type":"string"},"description":{"type":"string"},"due_date":{"type":"string"},"id":{"type":"string"},"issue_date":{"type":"string"},"last_status":{"$ref":"#/components/schemas/BillStatusReply"},"line_items":{"items":{"$ref":"#/components/schemas/LineItemReply"},"type":"array"},"number":{"type":"string"},"pay_date":{"type":"string"},"source":{"$ref":"#/components/schemas/BillSource"},"status":{"$ref":"#/components/schemas/BillStatus"},"updated_at":{"type":"string"},"vendor_id":{"type":"string"},"vendor_payments":{"items":{"$ref":"#/components/schemas/VendorPaymentReply"},"type":"array"}},"type":"object"},"BillStatusReply":{"description":"Bill status history entry","properties":{"created_at":{"type":"string"},"reason":{"type":"string"},"status":{"$ref":"#/components/schemas/BillStatus"},"user_id":{"type":"string"}},"type":"object"},"BillStatus":{"description":"Bill status enum","enum":["draft","needs_approval","processing","paid","deleted","failed"],"type":"string"},"LineItemReply":{"description":"Bill line item details","properties":{"description":{"type":"string"},"expense_account_id":{"type":"string"},"name":{"type":"string"},"quantity":{"type":"number"},"sequence":{"type":"integer"},"tax":{"type":"number"},"total":{"type":"number"},"unit_price":{"type":"number"},"unit_type":{"type":"string"}},"type":"object"},"BillSource":{"description":"Bill source enum","enum":["manual","quickbooks","ocr"],"type":"string"},"VendorPaymentReply":{"description":"Vendor payment details","properties":{"attempt_number":{"type":"integer"},"estimated_arrival_date":{"type":"string"},"failure_reason":{"type":"string"},"hold_until":{"type":"string"},"id":{"type":"string"},"payment_method_id":{"type":"string"},"payment_speed":{"$ref":"#/components/schemas/PaymentSpeedEnum"},"sent_at":{"type":"string"},"status":{"$ref":"#/components/schemas/VendorPaymentStatusEnum"}},"type":"object"},"PaymentSpeedEnum":{"description":"Payment speed enum","enum":["standard","next_day","same_day","instant"],"type":"string"},"VendorPaymentStatusEnum":{"description":"Vendor payment status enum","enum":["hold","waiting_pay_date","ready","processing","succeeded","failed"],"type":"string"}}},"paths":{"/bills":{"get":{"description":"Get a paginated list of bills with optional filtering","parameters":[{"schema":{"type":"integer","default":100},"description":"Number of items to return","in":"query","name":"limit"},{"schema":{"type":"string"},"description":"Cursor for forward pagination","in":"query","name":"after"},{"schema":{"type":"string"},"description":"Cursor for backward pagination","in":"query","name":"before"},{"schema":{"type":"string"},"description":"Filter by vendor ID","in":"query","name":"vendor_id"},{"schema":{"type":"string"},"description":"Filter by bill status (draft, needs_approval, processing, paid, deleted, failed)","in":"query","name":"status"},{"schema":{"type":"string"},"description":"Filter by bill number","in":"query","name":"bill_number"},{"schema":{"type":"string"},"description":"Filter by bill source (manual, quickbooks, ocr)","in":"query","name":"source"},{"schema":{"type":"boolean"},"description":"Include soft-deleted bills","in":"query","name":"include_deleted"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResponse-BillReply"}}}}},"summary":"List bills","tags":["Bills"]}}}}
```

## Create a bill

> Create a new bill. Optionally set status to "needs\_approval" to skip draft and submit directly for approval.

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["accounts_payable:write"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"BillReply":{"description":"Bill details","properties":{"amount":{"type":"number"},"created_at":{"type":"string"},"description":{"type":"string"},"due_date":{"type":"string"},"id":{"type":"string"},"issue_date":{"type":"string"},"last_status":{"$ref":"#/components/schemas/BillStatusReply"},"line_items":{"items":{"$ref":"#/components/schemas/LineItemReply"},"type":"array"},"number":{"type":"string"},"pay_date":{"type":"string"},"source":{"$ref":"#/components/schemas/BillSource"},"status":{"$ref":"#/components/schemas/BillStatus"},"updated_at":{"type":"string"},"vendor_id":{"type":"string"},"vendor_payments":{"items":{"$ref":"#/components/schemas/VendorPaymentReply"},"type":"array"}},"type":"object"},"BillStatusReply":{"description":"Bill status history entry","properties":{"created_at":{"type":"string"},"reason":{"type":"string"},"status":{"$ref":"#/components/schemas/BillStatus"},"user_id":{"type":"string"}},"type":"object"},"BillStatus":{"description":"Bill status enum","enum":["draft","needs_approval","processing","paid","deleted","failed"],"type":"string"},"LineItemReply":{"description":"Bill line item details","properties":{"description":{"type":"string"},"expense_account_id":{"type":"string"},"name":{"type":"string"},"quantity":{"type":"number"},"sequence":{"type":"integer"},"tax":{"type":"number"},"total":{"type":"number"},"unit_price":{"type":"number"},"unit_type":{"type":"string"}},"type":"object"},"BillSource":{"description":"Bill source enum","enum":["manual","quickbooks","ocr"],"type":"string"},"VendorPaymentReply":{"description":"Vendor payment details","properties":{"attempt_number":{"type":"integer"},"estimated_arrival_date":{"type":"string"},"failure_reason":{"type":"string"},"hold_until":{"type":"string"},"id":{"type":"string"},"payment_method_id":{"type":"string"},"payment_speed":{"$ref":"#/components/schemas/PaymentSpeedEnum"},"sent_at":{"type":"string"},"status":{"$ref":"#/components/schemas/VendorPaymentStatusEnum"}},"type":"object"},"PaymentSpeedEnum":{"description":"Payment speed enum","enum":["standard","next_day","same_day","instant"],"type":"string"},"VendorPaymentStatusEnum":{"description":"Vendor payment status enum","enum":["hold","waiting_pay_date","ready","processing","succeeded","failed"],"type":"string"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"},"CreateBillInput":{"description":"Bill creation request","properties":{"amount":{"type":"number"},"description":{"type":"string"},"due_date":{"type":"string"},"issue_date":{"type":"string"},"line_items":{"items":{"$ref":"#/components/schemas/BillLineItemInput"},"type":"array"},"number":{"type":"string"},"status":{"type":"string"},"vendor_id":{"type":"string"}},"type":"object"},"BillLineItemInput":{"description":"Bill line item input","properties":{"description":{"type":"string"},"expense_account_id":{"description":"ExpenseAccountID is an optional GL/expense account ID used to categorize this line item. Omit to leave it uncategorized.","type":"string"},"name":{"type":"string"},"quantity":{"type":"number"},"tax":{"type":"number"},"total":{"type":"number"},"unit_price":{"type":"number"},"unit_type":{"type":"string"}},"type":"object"}}},"paths":{"/bills":{"post":{"description":"Create a new bill. Optionally set status to \"needs_approval\" to skip draft and submit directly for approval.","responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillReply"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Create a bill","tags":["Bills"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateBillInput"}}},"description":"Bill information","required":true}}}}}
```

## Get a bill

> Get bill details by ID, including line items, payment status, and status history

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["accounts_payable:read"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"BillReply":{"description":"Bill details","properties":{"amount":{"type":"number"},"created_at":{"type":"string"},"description":{"type":"string"},"due_date":{"type":"string"},"id":{"type":"string"},"issue_date":{"type":"string"},"last_status":{"$ref":"#/components/schemas/BillStatusReply"},"line_items":{"items":{"$ref":"#/components/schemas/LineItemReply"},"type":"array"},"number":{"type":"string"},"pay_date":{"type":"string"},"source":{"$ref":"#/components/schemas/BillSource"},"status":{"$ref":"#/components/schemas/BillStatus"},"updated_at":{"type":"string"},"vendor_id":{"type":"string"},"vendor_payments":{"items":{"$ref":"#/components/schemas/VendorPaymentReply"},"type":"array"}},"type":"object"},"BillStatusReply":{"description":"Bill status history entry","properties":{"created_at":{"type":"string"},"reason":{"type":"string"},"status":{"$ref":"#/components/schemas/BillStatus"},"user_id":{"type":"string"}},"type":"object"},"BillStatus":{"description":"Bill status enum","enum":["draft","needs_approval","processing","paid","deleted","failed"],"type":"string"},"LineItemReply":{"description":"Bill line item details","properties":{"description":{"type":"string"},"expense_account_id":{"type":"string"},"name":{"type":"string"},"quantity":{"type":"number"},"sequence":{"type":"integer"},"tax":{"type":"number"},"total":{"type":"number"},"unit_price":{"type":"number"},"unit_type":{"type":"string"}},"type":"object"},"BillSource":{"description":"Bill source enum","enum":["manual","quickbooks","ocr"],"type":"string"},"VendorPaymentReply":{"description":"Vendor payment details","properties":{"attempt_number":{"type":"integer"},"estimated_arrival_date":{"type":"string"},"failure_reason":{"type":"string"},"hold_until":{"type":"string"},"id":{"type":"string"},"payment_method_id":{"type":"string"},"payment_speed":{"$ref":"#/components/schemas/PaymentSpeedEnum"},"sent_at":{"type":"string"},"status":{"$ref":"#/components/schemas/VendorPaymentStatusEnum"}},"type":"object"},"PaymentSpeedEnum":{"description":"Payment speed enum","enum":["standard","next_day","same_day","instant"],"type":"string"},"VendorPaymentStatusEnum":{"description":"Vendor payment status enum","enum":["hold","waiting_pay_date","ready","processing","succeeded","failed"],"type":"string"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"}}},"paths":{"/bills/{id}":{"get":{"description":"Get bill details by ID, including line items, payment status, and status history","parameters":[{"schema":{"type":"string"},"description":"Bill ID","in":"path","name":"id","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillReply"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Get a bill","tags":["Bills"]}}}}
```

## Delete a bill

> Soft-delete a bill. Cannot delete bills in PROCESSING or PAID status.

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["accounts_payable:write"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"DeleteBillReply":{"description":"Bill deletion result","properties":{"bill_id":{"type":"string"},"success":{"type":"boolean"}},"type":"object"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"}}},"paths":{"/bills/{id}":{"delete":{"description":"Soft-delete a bill. Cannot delete bills in PROCESSING or PAID status.","parameters":[{"schema":{"type":"string"},"description":"Bill ID","in":"path","name":"id","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteBillReply"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Delete a bill","tags":["Bills"]}}}}
```

## Update a bill

> Partially update bill details. Cannot update bills in PROCESSING or PAID status.

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["accounts_payable:write"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"BillReply":{"description":"Bill details","properties":{"amount":{"type":"number"},"created_at":{"type":"string"},"description":{"type":"string"},"due_date":{"type":"string"},"id":{"type":"string"},"issue_date":{"type":"string"},"last_status":{"$ref":"#/components/schemas/BillStatusReply"},"line_items":{"items":{"$ref":"#/components/schemas/LineItemReply"},"type":"array"},"number":{"type":"string"},"pay_date":{"type":"string"},"source":{"$ref":"#/components/schemas/BillSource"},"status":{"$ref":"#/components/schemas/BillStatus"},"updated_at":{"type":"string"},"vendor_id":{"type":"string"},"vendor_payments":{"items":{"$ref":"#/components/schemas/VendorPaymentReply"},"type":"array"}},"type":"object"},"BillStatusReply":{"description":"Bill status history entry","properties":{"created_at":{"type":"string"},"reason":{"type":"string"},"status":{"$ref":"#/components/schemas/BillStatus"},"user_id":{"type":"string"}},"type":"object"},"BillStatus":{"description":"Bill status enum","enum":["draft","needs_approval","processing","paid","deleted","failed"],"type":"string"},"LineItemReply":{"description":"Bill line item details","properties":{"description":{"type":"string"},"expense_account_id":{"type":"string"},"name":{"type":"string"},"quantity":{"type":"number"},"sequence":{"type":"integer"},"tax":{"type":"number"},"total":{"type":"number"},"unit_price":{"type":"number"},"unit_type":{"type":"string"}},"type":"object"},"BillSource":{"description":"Bill source enum","enum":["manual","quickbooks","ocr"],"type":"string"},"VendorPaymentReply":{"description":"Vendor payment details","properties":{"attempt_number":{"type":"integer"},"estimated_arrival_date":{"type":"string"},"failure_reason":{"type":"string"},"hold_until":{"type":"string"},"id":{"type":"string"},"payment_method_id":{"type":"string"},"payment_speed":{"$ref":"#/components/schemas/PaymentSpeedEnum"},"sent_at":{"type":"string"},"status":{"$ref":"#/components/schemas/VendorPaymentStatusEnum"}},"type":"object"},"PaymentSpeedEnum":{"description":"Payment speed enum","enum":["standard","next_day","same_day","instant"],"type":"string"},"VendorPaymentStatusEnum":{"description":"Vendor payment status enum","enum":["hold","waiting_pay_date","ready","processing","succeeded","failed"],"type":"string"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"},"PatchBillInput":{"description":"Bill patch request (partial update)","properties":{"amount":{"type":"number"},"description":{"type":"string"},"due_date":{"type":"string"},"issue_date":{"type":"string"},"line_items":{"$ref":"#/components/schemas/LineItemsUpdateInput"},"vendor_id":{"type":"string"}},"type":"object"},"LineItemsUpdateInput":{"description":"Line items update with optional replacement","properties":{"items":{"items":{"$ref":"#/components/schemas/BillLineItemInput"},"type":"array"},"replace":{"type":"boolean"}},"type":"object"},"BillLineItemInput":{"description":"Bill line item input","properties":{"description":{"type":"string"},"expense_account_id":{"description":"ExpenseAccountID is an optional GL/expense account ID used to categorize this line item. Omit to leave it uncategorized.","type":"string"},"name":{"type":"string"},"quantity":{"type":"number"},"tax":{"type":"number"},"total":{"type":"number"},"unit_price":{"type":"number"},"unit_type":{"type":"string"}},"type":"object"}}},"paths":{"/bills/{id}":{"patch":{"description":"Partially update bill details. Cannot update bills in PROCESSING or PAID status.","parameters":[{"schema":{"type":"string"},"description":"Bill ID","in":"path","name":"id","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillReply"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Update a bill","tags":["Bills"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchBillInput"}}},"description":"Bill patch information","required":true}}}}}
```

## Get bill document

> Get the download URL for a bill's attached document

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["accounts_payable:read"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"BillDocumentReply":{"description":"Bill document download details","properties":{"download_url":{"type":"string"},"filename":{"type":"string"},"mime_type":{"type":"string"}},"type":"object"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"}}},"paths":{"/bills/{id}/document":{"get":{"description":"Get the download URL for a bill's attached document","parameters":[{"schema":{"type":"string"},"description":"Bill ID","in":"path","name":"id","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillDocumentReply"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Get bill document","tags":["Bills"]}}}}
```

## Update bill pay date

> Set or update the scheduled payment date for a bill

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["accounts_payable:write"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"UpdatePayDateReply":{"description":"Pay date update result","properties":{"bill_id":{"type":"string"}},"type":"object"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"},"UpdatePayDateInput":{"description":"Pay date update request","properties":{"pay_date":{"type":"string"}},"type":"object"}}},"paths":{"/bills/{id}/pay-date":{"post":{"description":"Set or update the scheduled payment date for a bill","parameters":[{"schema":{"type":"string"},"description":"Bill ID","in":"path","name":"id","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePayDateReply"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Update bill pay date","tags":["Bills"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePayDateInput"}}},"description":"Pay date","required":true}}}}}
```

## Reject a bill

> Reject a bill in NEEDS\_APPROVAL status, transitioning it back to DRAFT

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["accounts_payable:write"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"RejectBillReply":{"description":"Bill rejection result","properties":{"bill_id":{"type":"string"}},"type":"object"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"},"RejectBillInput":{"description":"Bill rejection request","properties":{"reason":{"type":"string"}},"type":"object"}}},"paths":{"/bills/{id}/reject":{"post":{"description":"Reject a bill in NEEDS_APPROVAL status, transitioning it back to DRAFT","parameters":[{"schema":{"type":"string"},"description":"Bill ID","in":"path","name":"id","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RejectBillReply"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Reject a bill","tags":["Bills"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RejectBillInput"}}},"description":"Rejection reason","required":true}}}}}
```

## Submit bill for approval

> Transition a bill from DRAFT to NEEDS\_APPROVAL status

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["accounts_payable:write"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"SubmitBillReply":{"description":"Bill submission result","properties":{"bill_id":{"type":"string"},"success":{"type":"boolean"}},"type":"object"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"}}},"paths":{"/bills/{id}/submit":{"post":{"description":"Transition a bill from DRAFT to NEEDS_APPROVAL status","parameters":[{"schema":{"type":"string"},"description":"Bill ID","in":"path","name":"id","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitBillReply"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Submit bill for approval","tags":["Bills"]}}}}
```

## Bulk delete bills

> Soft-delete multiple bills in a single request

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["accounts_payable:write"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"BulkOperationReply":{"description":"Bulk operation results","properties":{"results":{"items":{"$ref":"#/components/schemas/BulkResultReply"},"type":"array"}},"type":"object"},"BulkResultReply":{"description":"Bulk operation per-item result","properties":{"bill_id":{"type":"string"},"error_reason":{"type":"string"},"success":{"type":"boolean"}},"type":"object"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"},"BulkDeleteBillsInput":{"description":"Bulk bill deletion request","properties":{"bill_ids":{"items":{"type":"string"},"type":"array"}},"type":"object"}}},"paths":{"/bills/bulk-delete":{"post":{"description":"Soft-delete multiple bills in a single request","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkOperationReply"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Bulk delete bills","tags":["Bills"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkDeleteBillsInput"}}},"description":"Bill IDs to delete","required":true}}}}}
```

## Bulk submit bills for approval

> Submit multiple bills for approval in a single request

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["accounts_payable:write"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"BulkOperationReply":{"description":"Bulk operation results","properties":{"results":{"items":{"$ref":"#/components/schemas/BulkResultReply"},"type":"array"}},"type":"object"},"BulkResultReply":{"description":"Bulk operation per-item result","properties":{"bill_id":{"type":"string"},"error_reason":{"type":"string"},"success":{"type":"boolean"}},"type":"object"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"},"BulkSubmitBillsInput":{"description":"Bulk bill submission request","properties":{"bill_ids":{"items":{"type":"string"},"type":"array"}},"type":"object"}}},"paths":{"/bills/bulk-submit":{"post":{"description":"Submit multiple bills for approval in a single request","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkOperationReply"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Bulk submit bills for approval","tags":["Bills"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkSubmitBillsInput"}}},"description":"Bill IDs to submit","required":true}}}}}
```

## Upload bill document with OCR

> Upload a document (PDF, PNG, JPEG), extract data via OCR, and create a bill

```json
{"openapi":"3.1.1","info":{"title":"Alternative Payments","version":"1.2.0"},"servers":[{"url":"http://public-api.alternativepayments.io"}],"security":[{"OAuth2ClientCredentials":["accounts_payable:write"]}],"components":{"securitySchemes":{"OAuth2ClientCredentials":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"read":"Read access","write":"Write access"}}}}},"schemas":{"UploadBillDocumentReply":{"description":"Bill upload result with OCR data","properties":{"bill_id":{"type":"string"},"bill_number":{"type":"string"},"document_path":{"type":"string"},"extracted_data":{"$ref":"#/components/schemas/ExtractedBillDataReply"},"warnings":{"items":{"type":"string"},"type":"array"}},"type":"object"},"ExtractedBillDataReply":{"description":"Extracted bill data from OCR","properties":{"description":{"type":"string"},"due_date":{"type":"string"},"invoice_number":{"type":"string"},"issue_date":{"type":"string"},"line_items":{"items":{"$ref":"#/components/schemas/ExtractedLineItemReply"},"type":"array"},"total":{"type":"number"},"vendor_email":{"type":"string"},"vendor_name":{"type":"string"}},"type":"object"},"ExtractedLineItemReply":{"description":"Extracted line item from OCR","properties":{"description":{"type":"string"},"name":{"type":"string"},"quantity":{"type":"number"},"total":{"type":"number"},"unit_price":{"type":"number"}},"type":"object"},"HttpError":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"validation_errors":{"additionalProperties":{"type":"string"},"type":"object"}},"type":"object"},"UploadBillDocumentInput":{"description":"Bill document upload request","properties":{"content":{"type":"string"},"content_type":{"type":"string"},"filename":{"type":"string"}},"type":"object"}}},"paths":{"/bills/upload":{"post":{"description":"Upload a document (PDF, PNG, JPEG), extract data via OCR, and create a bill","responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadBillDocumentReply"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}}}},"summary":"Upload bill document with OCR","tags":["Bills"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadBillDocumentInput"}}},"description":"Document to upload (base64-encoded content)","required":true}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.alternativepayments.io/api-reference/bills.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.