> ## Documentation Index > Fetch the complete documentation index at: https://broker-docs.newyorkcityservers.com/llms.txt > Use this file to discover all available pages before exploring further. # Invoices Report > Generate an invoice report and send it to email recipients. Generate a report for the `paid` and `pending` invoices in a date range. The endpoint sends an Excel `.xls` file to each valid recipient. It does not return the file in the HTTP response. The full endpoint is `POST /api/v1/reports/invoices`. ## Errors Error responses use `success: false` and an `error` object. | HTTP status | Error code | Message or cause | | ----------- | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `400` | `invalid_request` | The body is not valid JSON. The message is `Invalid JSON in request body`. | | `400` | `missing_parameter` | `recipients` is missing or is `null`. The response details list `recipients` as required. | | `400` | `invalid_parameter` | `recipients` is not an array, an item is not a string, an address is invalid, or no nonempty address remains. The response details contain `max_recipients: 10`. | | `400` | `too_many_recipients` | More than 10 unique normalized recipients remain. | | `400` | `missing_parameter` | `start_date` or `end_date` is missing or empty. The response details list both date fields as required. | | `400` | `invalid_parameter` | A date does not use `YYYY-MM-DD`, a date value cannot be parsed, or `start_date` is after `end_date`. | | `400` | `no_data` | No `paid` or `pending` invoice matches the date range. The response details contain the requested dates. | | `401` | `authentication_failed` | The Bearer token is missing, invalid, inactive, or expired. | | `403` | `insufficient_permissions` | The request IP is not allowed, or the key does not have `reports:generate` or `admin:full`. | | `429` | `rate_limit_exceeded` | The key reached its rate limit. Use the `Retry-After` response header. | | `500` | `server_error` | The API could not get broker configuration, get invoice data, generate the report, or complete an internal operation. Individual email send failures use the recipient counts in an HTTP `200` response. | ## OpenAPI ````yaml api/openapi.yaml POST /v1/reports/invoices openapi: 3.1.0 info: title: Broker API version: 1.0.0 description: API for broker-scoped service, request, and report operations. servers: - url: https://brokers.newyorkcityservers.com/api description: Broker Panel API security: - bearerAuth: [] tags: - name: Authentication - name: Services - name: Requests - name: Reports paths: /v1/reports/invoices: post: tags: - Reports summary: Invoices Report description: >- Generates a paid/pending invoice report for a date range and emails it to normalized recipients. Requires `reports:generate` or `admin:full`. operationId: sendInvoicesReport requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/InvoicesReportRequest' example: recipients: - accounts@example.com - owner@example.com start_date: '2026-01-01' end_date: '2026-01-31' responses: '200': description: Report send attempts completed. content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - type: object required: - data properties: data: $ref: '#/components/schemas/InvoicesReportResult' example: success: true data: report_type: invoices total_invoices: 28 paid_invoices: 22 unpaid_invoices: 6 recipients_sent: 2 recipients_failed: 0 date_range: start: '2026-01-01' end: '2026-01-31' generated_at: '2026-02-01T10:30:00.000Z' '400': description: >- Codes `invalid_request`, `missing_parameter`, `invalid_parameter`, `too_many_recipients`, or `no_data`. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalidDates: value: success: false error: code: invalid_parameter message: start_date must be before or equal to end_date noData: value: success: false error: code: no_data message: No invoices found for the specified date range details: start_date: '2026-01-01' end_date: '2026-01-31' '401': $ref: '#/components/responses/AuthenticationError' '403': $ref: '#/components/responses/PermissionError' '429': $ref: '#/components/responses/RateLimitError' '500': $ref: '#/components/responses/ServerError' components: schemas: InvoicesReportRequest: type: object required: - recipients - start_date - end_date properties: recipients: $ref: '#/components/schemas/ReportRecipients' start_date: type: string format: date end_date: type: string format: date SuccessEnvelope: type: object required: - success properties: success: type: boolean const: true message: type: string pagination: $ref: '#/components/schemas/Pagination' InvoicesReportResult: type: object required: - report_type - total_invoices - paid_invoices - unpaid_invoices - recipients_sent - recipients_failed - date_range - generated_at properties: report_type: type: string const: invoices total_invoices: type: integer minimum: 0 paid_invoices: type: integer minimum: 0 unpaid_invoices: type: integer minimum: 0 recipients_sent: type: integer minimum: 0 recipients_failed: type: integer minimum: 0 date_range: type: object required: - start - end properties: start: type: string format: date end: type: string format: date generated_at: type: string format: date-time ErrorResponse: type: object required: - success - error properties: success: type: boolean const: false error: $ref: '#/components/schemas/Error' ReportRecipients: type: array minItems: 1 items: type: string description: >- Items are trimmed and lowercased; empty strings are ignored and duplicates are removed. Every remaining value must be an email address, and at most 10 unique nonempty recipients may remain. Pagination: type: object required: - page - perPage - total - totalPages properties: page: type: integer minimum: 1 perPage: type: integer minimum: 1 maximum: 100 total: type: integer minimum: 0 totalPages: type: integer minimum: 0 Error: type: object required: - code - message properties: code: type: string message: type: string details: type: object additionalProperties: true responses: AuthenticationError: description: >- Code `authentication_failed` for a missing, malformed, invalid, inactive, or expired API key. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: authentication_failed message: Invalid API key PermissionError: description: >- Code `insufficient_permissions` when the request IP is not whitelisted or a required scope is missing. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: insufficient_permissions message: IP address not whitelisted RateLimitError: description: Code `rate_limit_exceeded` when the API key exceeds its rate limit. headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer minimum: 1 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: rate_limit_exceeded message: Rate limit exceeded ServerError: description: >- Code `server_error` when authentication or internal processing cannot complete. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: server_error message: Internal server error securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API key description: >- Send the API key in the Authorization bearer header. Production keys begin with `sk_live_`. ````