> ## Documentation Index > Fetch the complete documentation index at: https://docs.salesbricks.com/llms.txt > Use this file to discover all available pages before exploring further. # Finalize an invoice > Issues a draft invoice. Final tax is committed, the date of issue and due date are stamped, the invoice leaves draft for its terminal status, and it is sent to the customer's invoice recipients. Only drafts can be issued. `due_date_basis` is optional — omit it and the invoice inherits the order's default, or keeps a due date already set by editing it. Sending a basis re-derives the due date and replaces an edited one. Send `CUSTOM` with a `due_at` to name the due date outright; either one without the other is rejected. ## Waiting for the document By default the request is held until the invoice's PDF has rendered, so a `200` means the invoice is issued and its document is ready to retrieve. Pass `async=true` to queue the issue and get an answer immediately, with the draft as it stands. Poll the invoice to see it issued. A `202` means the work is still in flight: with `async=true` the invoice has been accepted for issuing, and without it the invoice is issued but its PDF is still rendering. Neither is a failure — an invoice that could not be issued at all comes back `400`. ## OpenAPI ````yaml https://api.salesbricks.com/api/v2/openapi.yaml post /invoices/{invoice_id}/finalize openapi: 3.0.3 info: title: Salesbricks REST API version: 2.0.0 description: API reference for external integrations servers: - url: https://api.salesbricks.com/api/v2 description: Production - url: https://api.staging.salesbricks.com/api/v2 description: Staging security: - ApiKeyAuth: [] tags: - name: Subscriptions description: >- Operations related to subscription management, including creation, updates, and retrieving subscription details. Subscriptions can be upgraded to add / remove add-ons by using the POST /subscriptions/{subscription_id}/upgrade endpoint and can be recasted for replacing the current agreement using the POST /subscriptions/{subscription_id}/recast endpoint - name: Subscription Milestones description: >- Operations for listing and completing milestone bricks — bricks billed when the work they cover is delivered rather than on the subscription's schedule. Completing one either raises a standalone invoice immediately or bills on the subscription's next scheduled invoice. - name: Customers description: >- Operations related to customer management, including creation, updates, and managing customer person objects. - name: Invoices description: Operations related to subscription's invoicing details. - name: Plans description: >- Operations related to listing and getting plan details including bricks in the plan. - name: Payment Methods description: Operations related to subscription's payment method. paths: /invoices/{invoice_id}/finalize: post: tags: - Invoices summary: Finalize an invoice description: >- Issues a draft invoice. Final tax is committed, the date of issue and due date are stamped, the invoice leaves draft for its terminal status, and it is sent to the customer's invoice recipients. Only drafts can be issued. `due_date_basis` is optional — omit it and the invoice inherits the order's default, or keeps a due date already set by editing it. Sending a basis re-derives the due date and replaces an edited one. Send `CUSTOM` with a `due_at` to name the due date outright; either one without the other is rejected. ## Waiting for the document By default the request is held until the invoice's PDF has rendered, so a `200` means the invoice is issued and its document is ready to retrieve. Pass `async=true` to queue the issue and get an answer immediately, with the draft as it stands. Poll the invoice to see it issued. A `202` means the work is still in flight: with `async=true` the invoice has been accepted for issuing, and without it the invoice is issued but its PDF is still rendering. Neither is a failure — an invoice that could not be issued at all comes back `400`. operationId: finalizeInvoice parameters: - in: query name: async schema: type: boolean description: >- Set to true to queue the issue and answer immediately instead of waiting for the invoice's PDF. - in: path name: invoice_id schema: type: string pattern: ^([a-zA-Z\d\-]+)$ required: true requestBody: content: application/json: schema: $ref: '#/components/schemas/FinalizeInvoiceRequest' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/FinalizeInvoiceRequest' multipart/form-data: schema: $ref: '#/components/schemas/FinalizeInvoiceRequest' responses: '200': content: application/json: schema: $ref: '#/components/schemas/Invoice' description: '' '202': content: application/json: schema: $ref: '#/components/schemas/Invoice' description: '' '400': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: BadRequestResponse: value: error: code: ERR_BAD_REQUEST message: >- Bad request — the input payload is malformed, missing required fields, or contains invalid data. summary: Bad Request Response description: '' '404': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: NotFoundResponse: value: error: code: ERR_NOT_FOUND message: >- Not found — the resource you are looking for does not exist. summary: Not Found Response description: '' components: schemas: FinalizeInvoiceRequest: type: object properties: due_date_basis: enum: - ISSUE_DATE - SERVICE_PERIOD - CUSTOM type: string x-spec-enum-id: 16da8029ddd46fbc nullable: true description: >- What the issued invoice's due date follows. Omit it to inherit the order's default — unless the invoice already carries a due date you set by editing it, which is kept. Sending a basis re-derives the due date and replaces an edited one. `CUSTOM` names the date outright and must be sent with `due_at`. * `ISSUE_DATE` - Issue date * `SERVICE_PERIOD` - Service period * `CUSTOM` - Custom due_at: type: string format: date nullable: true description: >- The due date to issue under. Only valid with a `CUSTOM` `due_date_basis`, and cannot be earlier than the date of issue. Invoice: type: object properties: invoice_id: type: string format: uuid description: >- Unique identifier for the invoice. If the id is null, this is an estimate subscription_id: type: string format: uuid description: >- ID of the subscription this invoice belongs to. Null for standalone (one-off) invoices. customer_id: type: string format: uuid description: >- ID of the end customer this invoice is for — the company that consumes the subscription. Never collect or charge payment methods against this id: on a partner-billed invoice the paying party is a different company, and `billed_company_id` is always the id to collect against. billed_company_id: type: string format: uuid description: >- ID of the company actually billed for this invoice — the party whose Stripe customer `POST /invoices/{invoice_id}/pay` charges. Equal to `customer_id` unless the invoice is partner-billed, in which case it is the partner's company. Collect and list payment methods against this id, never `customer_id`. Always present and never null, including on the renewal estimate returned by `GET /subscriptions/{subscription_id}/invoices/next`, which resolves the company its renewal would bill. customer_name: type: string description: Name of the customer who will pay this invoice invoice_number: type: string description: >- Short form identifier for the invoice. If the invoice_number is null, this is an estimate time_zone: type: string description: Invoice timezone due_at: type: string format: date-time description: The date on which this invoice is expected to be paid by. bill_at: type: string format: date-time description: >- The date on which this invoice will be issued and potentially charged. issued_at: type: string format: date-time description: The date on which this invoice was issued. status: type: string description: > Current status of the invoice. One of: - `MUTED` — Invoice will not be sent. Muted invoices come from migration cut-overs or from muting invoices in the product settings. - `SCHEDULED` — Scheduled to be issued on a future date. - `OUTSTANDING` — Issued and awaiting payment. - `DUE` — Payment is due. - `PAST_DUE` — Payment is past its due date. - `PAID` — Fully paid. - `PARTIALLY_PAID` — Partially paid, with a remaining balance. - `ADJUSTED` — Adjusted after issuance. - `CREDITED` — Settled by applying credit. - `UNPAID` — Unpaid. - `PAUSED` — Collection is paused. - `VOIDED` — Voided and no longer collectible. fully_paid_at: type: string format: date-time description: The date on which this invoice was fully paid. grand_total: type: integer description: >- Total amount due for this invoice. Invoices that have not been generated yet (e.g. `SCHEDULED`) report the total expected at the time they were created. That figure does NOT include usage metered since — a usage invoice whose meters have not been priced reports 0. Pass `?calculate_expected_usage=true` to re-price against the order and include estimated usage instead; it is slower, so it is off by default on list endpoints. remaining_amount: type: integer description: Remaining amount for this invoice. currency: type: string description: The currency in which the invoice is denominated (e.g., USD, EUR). is_renewal_estimate: type: boolean description: >- This is an estimate for a renewal that has not yet closed, but is expected to. payments: type: array items: $ref: '#/components/schemas/Payment' description: All payments made against this invoice, newest first. attachments: type: array items: {} description: >- Current attachments for this invoice as a flat array. Each item includes 'target' field indicating invoice or subscription level. Sorted by unified order. line_items: type: array items: $ref: '#/components/schemas/InvoiceLineItemOutput' description: Line item breakdown for this invoice metadata: description: Optional metadata stored against the invoice. purchase_order: allOf: - $ref: '#/components/schemas/PurchaseOrderOutput' nullable: true description: >- Purchase order shown on this invoice: the invoice's own purchase order when it has one, otherwise the subscription's. Matches the PO printed on the invoice PDF. Null when neither carries one. required: - bill_at - billed_company_id - currency - customer_id - due_at - fully_paid_at - grand_total - invoice_id - invoice_number - is_renewal_estimate - issued_at - remaining_amount - status - subscription_id ErrorResponse: type: object description: >- Standardizes API error responses with a consistent structure containing error code and message. properties: error: $ref: '#/components/schemas/Error' required: - error Payment: type: object properties: payment_id: type: string format: uuid readOnly: true description: Unique identifier for the payment invoice_number: type: string nullable: true readOnly: true description: >- The invoice number this payment was made against, snapshotted from the invoice version current when the payment was recorded — it does not change when the invoice is later regenerated, so it may differ from the invoice's top-level `invoice_number`. Falls back to the invoice's current number when no version is linked. Join payments to invoices by ID, not by number. invoice_version_id: type: string format: uuid readOnly: true nullable: true description: >- Identifier of the invoice version this payment was made against — the version current when the payment was recorded. Null only when the invoice has no versions (it was never generated). paid_amount: type: integer readOnly: true nullable: true description: The amount paid paid_at: type: string format: date-time readOnly: true nullable: true description: the date at which this payment was paid currency: type: string readOnly: true description: The currency in which the payment is denominated (e.g., USD, EUR) error: type: string readOnly: true nullable: true description: Any errors that occured during this payment processing required: - currency - error - invoice_number - invoice_version_id - paid_amount - paid_at - payment_id InvoiceLineItemOutput: type: object properties: brick_name: type: string description: Name of the brick brick_id: type: string nullable: true description: Unique identifier of the brick quantity: oneOf: - type: integer - type: number format: double description: Quantity of units. Fractional quantities are returned as a decimal readOnly: true tax: type: integer description: Tax amount in minor currency units grand_total: type: integer description: Grand total in minor currency units starts_at: type: string format: date-time nullable: true description: Start of the period this line item covers ends_at: type: string format: date-time nullable: true description: End of the period this line item covers required: - brick_id - brick_name - ends_at - grand_total - quantity - starts_at - tax PurchaseOrderOutput: type: object description: A purchase order provided by the buyer. properties: code: type: string nullable: true description: Internal identifier of the Purchase Order provided by Buyer required: - code Error: type: object description: >- Represents individual error details with a standardized code and descriptive message. properties: code: enum: - ERR_NOT_FOUND - ERR_BAD_REQUEST - ERR_SERVER_ERROR type: string x-spec-enum-id: dc5a5d6feae1b697 description: >- Error code indicating the type of error: NOT_FOUND for missing resources, BAD_REQUEST for invalid input, SERVER_ERROR for internal server issues * `ERR_NOT_FOUND` - ERR_NOT_FOUND * `ERR_BAD_REQUEST` - ERR_BAD_REQUEST * `ERR_SERVER_ERROR` - ERR_SERVER_ERROR message: type: string error_id: type: string format: uuid description: >- Correlation handle for SERVER_ERROR responses — quote this when contacting support; it joins to the structured server log line for the failure. Not present on 4xx responses. required: - code - message securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-SALESBRICKS-KEY description: API key for authentication ```` ## Related topics - [Your email notifications](/settings/notifications/your-email-notifications.md) - [Regenerate an invoice](/api-reference/invoices/regenerate-an-invoice.md) - [invoice.start](/api-reference/webhooks/invoice/start.md)