> ## Documentation Index > Fetch the complete documentation index at: https://docs.go.aiinsurance.io/llms.txt > Use this file to discover all available pages before exploring further. # Replace Quote Invoice Settings > **Quote door.** A quote owns its invoices, and its settings are what generating them reads, before the quote is bound or as it binds. This replaces the quote's settings and leaves the plan on the quote as it is. The body is the whole settings object and every field is required: a PUT replaces them all. Choose payees by policy invoice type name. A type you leave out gets its payee when invoices are generated, as [Quote invoicing](/api-reference/invoicing/quote-invoicing) explains. The one schedule sent replaces any per-invoice-type schedules from older company defaults. Settings change no invoices on their own. To put invoices on the quote, call [Generate Quote Invoices](/api-reference/invoicing/generate-quote-invoices) next. The Billing step in the app shows and saves the same settings. **Refusals.** A body that breaks a rule returns `400` naming the field: an unknown or missing field; an `installmentCount` other than 1 or `null` with `upfront`; a `downPayment` with `upfront` or with one installment; a value out of range; a `group` listed twice or that is not a live policy invoice type; a `payeeId` that the type's invoices cannot be issued to. Nothing is saved. With policy invoicing disabled, this returns `403 finv2-policy-invoicing-disabled`. A bound or cancelled quote returns `409`. Every quote type takes settings: new business, renewal, endorsement, cancellation and reinstatement. **Required permission:** `quote.edit` ## OpenAPI ````yaml /openapi/generated-external-api.yaml put /api/v1/companies/{companyId}/quotes/{quoteId}/invoicing/settings openapi: 3.0.3 info: title: AI Insurance External API description: External API for AI Insurance platform version: 1.0.0 contact: email: support@aiinsurance.io servers: - url: https://go.aiinsurance.io description: Production security: - ApiKeyAuth: [] paths: /api/v1/companies/{companyId}/quotes/{quoteId}/invoicing/settings: put: tags: - Policy Invoicing summary: Replace Quote Invoice Settings description: > **Quote door.** A quote owns its invoices, and its settings are what generating them reads, before the quote is bound or as it binds. This replaces the quote's settings and leaves the plan on the quote as it is. The body is the whole settings object and every field is required: a PUT replaces them all. Choose payees by policy invoice type name. A type you leave out gets its payee when invoices are generated, as [Quote invoicing](/api-reference/invoicing/quote-invoicing) explains. The one schedule sent replaces any per-invoice-type schedules from older company defaults. Settings change no invoices on their own. To put invoices on the quote, call [Generate Quote Invoices](/api-reference/invoicing/generate-quote-invoices) next. The Billing step in the app shows and saves the same settings. **Refusals.** A body that breaks a rule returns `400` naming the field: an unknown or missing field; an `installmentCount` other than 1 or `null` with `upfront`; a `downPayment` with `upfront` or with one installment; a value out of range; a `group` listed twice or that is not a live policy invoice type; a `payeeId` that the type's invoices cannot be issued to. Nothing is saved. With policy invoicing disabled, this returns `403 finv2-policy-invoicing-disabled`. A bound or cancelled quote returns `409`. Every quote type takes settings: new business, renewal, endorsement, cancellation and reinstatement. **Required permission:** `quote.edit` operationId: putQuoteInvoiceSettings parameters: - $ref: '#/components/parameters/companyId' - $ref: '#/components/parameters/quoteIdPath' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/QuoteInvoiceSettings' examples: quarterly: summary: Four quarterly installments, sent two weeks early value: schedule: paymentPeriod: quarterly installmentCount: 4 firstDueDate: '2026-01-01' owedLeadTimeDays: 14 avoidWeekendSends: true downPayment: null payees: - group: Policy Invoice payeeId: 550e8400-e29b-41d4-a716-446655440010 endorsementHandling: mode: void status: scheduled monthlyWithDownPayment: summary: Monthly to the end of the term, 25 percent down value: schedule: paymentPeriod: monthly installmentCount: null firstDueDate: '2026-01-15' owedLeadTimeDays: 7 avoidWeekendSends: false downPayment: percent: 25 payees: [] endorsementHandling: mode: keep status: paid responses: '200': description: The quote's invoicing, with the new settings. content: application/json: schema: $ref: '#/components/schemas/QuoteInvoicing' examples: quarterlySaved: summary: Quarterly settings saved; no plan yet value: quoteId: 550e8400-e29b-41d4-a716-446655440002 settings: schedule: paymentPeriod: quarterly installmentCount: 4 firstDueDate: '2026-01-01' owedLeadTimeDays: 14 avoidWeekendSends: true downPayment: null payees: - group: Policy Invoice payeeId: 550e8400-e29b-41d4-a716-446655440010 endorsementHandling: mode: void status: scheduled settingsSource: quote plan: null '400': description: The body breaks a settings rule, naming the field. Nothing is saved. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: downPaymentWithUpfront: summary: A down payment on a single payment value: error: code: VALIDATION_ERROR message: >- schedule.downPayment: A down payment needs installments: choose quarterly or monthly, or send downPayment null. userMessages: - >- A down payment needs installments: choose quarterly or monthly, or send downPayment null. details: - field: schedule.downPayment message: >- A down payment needs installments: choose quarterly or monthly, or send downPayment null. unknownInvoiceType: summary: A payee for an invoice type the company does not have value: error: code: VALIDATION_ERROR message: >- payees.0.group: “Broker Invoice” is not a live policy invoice type of this company. Live types: “Policy Invoice”. userMessages: - >- “Broker Invoice” is not a live policy invoice type of this company. Live types: “Policy Invoice”. details: - field: payees.0.group message: >- “Broker Invoice” is not a live policy invoice type of this company. Live types: “Policy Invoice”. '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/ForbiddenQuoteInvoicing' '404': description: No quote with the given id exists for this company. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: quoteNotFound: summary: Quote not found value: error: code: NotFoundError message: Quote not found userMessages: - Quote not found '409': $ref: '#/components/responses/QuoteInvoicingClosed' '500': $ref: '#/components/responses/InternalServerError' components: parameters: companyId: name: companyId in: path required: true schema: type: string format: uuid description: Company identifier quoteIdPath: name: quoteId in: path required: true schema: type: string format: uuid description: Quote identifier schemas: QuoteInvoiceSettings: type: object additionalProperties: false description: >- The settings a quote generates its invoices from. A PUT sends every field and replaces them all. A GET returns the same shape, so you can change a field of a GET's `settings` and send the object back. required: - schedule - payees - endorsementHandling properties: schedule: type: object additionalProperties: false description: When the new invoices fall due and how they are sent. required: - paymentPeriod - installmentCount - firstDueDate - owedLeadTimeDays - avoidWeekendSends - downPayment properties: paymentPeriod: type: string enum: - upfront - quarterly - monthly description: How often installments fall due. `upfront` is a single payment. installmentCount: type: integer minimum: 1 maximum: 120 nullable: true description: >- How many installments. `null` schedules as many as fall due before the term ends. With `upfront`, send `1` or `null`. firstDueDate: type: string format: date description: >- The first installment's due date. Each later one falls due three months (quarterly) or one month (monthly) after the one before. owedLeadTimeDays: type: integer minimum: 0 maximum: 3650 description: >- How many days before its due date an installment is sent and becomes owed. avoidWeekendSends: type: boolean description: >- Move a send date that falls on a Saturday or Sunday back to the Friday before. downPayment: type: object nullable: true additionalProperties: false minProperties: 1 maxProperties: 1 description: >- A larger first installment, or `null` for equal installments. Send exactly one of `percent` and `amountCents`. A down payment needs at least two installments, so it must be `null` with `upfront` or with an `installmentCount` of 1. properties: percent: type: number minimum: 0 exclusiveMinimum: true maximum: 100 description: >- A percent of the receivable amount being invoiced, above 0 and at most 100, with up to two decimal places. amountCents: type: integer minimum: 1 description: An amount in cents, above 0. payees: type: array description: >- The payee chosen for each policy invoice type, by the type's name. List a type at most once; a type you leave out gets its payee when invoices are generated: the payee of the plan on the quote, then, on an endorsement, cancellation or reinstatement, the payee of the policy's current invoices of that type, then the type's configured payee. A GET lists only the payees chosen on the quote. items: type: object additionalProperties: false required: - group - payeeId properties: group: type: string minLength: 1 description: A live policy invoice type's name. payeeId: type: string format: uuid description: >- The Person, Organization or Exposure the type's invoices are issued to: a record of this company of a kind the type's payee settings allow. endorsementHandling: type: object description: >- What generating does with the policy's existing invoices on an endorsement, cancellation or reinstatement. `void` voids the invoices with the given status (`scheduled`, `owed`, or `all`); `keep` keeps them and voids the rest; `manual` keeps every invoice. Paid invoices and invoices with payments are never voided. Kept invoices count toward the billing, so new invoices bill only what they leave. oneOf: - type: object additionalProperties: false required: - mode - status properties: mode: type: string enum: - void status: type: string enum: - scheduled - owed - all - type: object additionalProperties: false required: - mode - status properties: mode: type: string enum: - keep status: type: string enum: - paid - owed - all - type: object additionalProperties: false required: - mode properties: mode: type: string enum: - manual QuoteInvoicing: type: object additionalProperties: false description: >- A quote's invoicing: the settings it generates invoices from and the plan saved on it. Binding the quote uses them. Every quote invoicing endpoint returns this. required: - quoteId - settings - settingsSource - plan properties: quoteId: type: string format: uuid settings: $ref: '#/components/schemas/QuoteInvoiceSettings' settingsSource: type: string enum: - quote - company-defaults description: >- Where `settings` come from. `quote` once the quote has settings of its own: saved with Replace Quote Invoice Settings, kept by Generate Quote Invoices, or saved in the app's Billing step. A plan attached without settings counts too, because its schedule is what `settings` shows. `company-defaults` while nothing on the quote sets them: `settings` are the company's payment defaults, applied to this quote. plan: description: The plan saved on the quote, or `null` when it holds none. anyOf: - $ref: '#/components/schemas/PolicyInvoiceTransactionPlan' - type: object nullable: true enum: - null ErrorResponse: type: object description: Standard error response for all external API endpoints required: - error properties: error: type: object required: - code - message properties: code: type: string description: Machine-readable error code example: VALIDATION_ERROR message: type: string description: Human-readable error message example: 'submissionId: Required field is missing' userMessages: type: array description: >- Clean, verbatim-displayable messages — one entry per failure, free of error-code tags, field paths, and internal noise. Suitable for showing to end users as-is. items: type: string example: - Exposures of type 'company' require an address details: type: array description: Additional details for validation errors (field-level errors) items: type: object properties: field: type: string description: The field that caused the error example: submissionId code: type: string description: Stable problem code for this individual validation failure example: BLANK_LIST_ELEMENT reason: type: string description: Stable reason the value violates its canonical contract example: blank-list-element expected: type: string description: The expected canonical value contract example: nonblank trimmed string message: type: string description: Description of the field error example: Required field is missing PolicyInvoiceTransactionPlan: type: object additionalProperties: false required: - incurredDate - voidInvoices - creates properties: incurredDate: type: string format: date description: >- Explicit recognition date for non-scheduled creates. It is never inferred from a transaction effective date or the server clock. voidInvoices: type: array items: $ref: '#/components/schemas/PolicyInvoiceBatchVoid' creates: type: array items: $ref: '#/components/schemas/PolicyInvoiceBatchCreate' description: >- A fully explicit, detached policy-invoice batch. Existing invoices not named in voidInvoices are kept. The complete kept-plus-created set must conserve each line item of the policy's stated billing. With invoicing enabled, a line item a kept invoice carries but billing omits conserves at 0: a create may credit it on the same line with a negative amount. PolicyInvoiceBatchVoid: type: object additionalProperties: false required: - invoiceId - headJournalId properties: invoiceId: type: string format: uuid headJournalId: type: string format: uuid description: >- The invoice watermark read while composing the plan. A stale watermark rejects the whole batch with 409. PolicyInvoiceBatchCreate: type: object additionalProperties: false required: - group - lineItems properties: group: type: string minLength: 1 description: >- Policy invoice type name. Pricing-fallback plans use the fixed Policy Invoice type; Billing Aggregate plans use each line's native invoiceType. dueDate: type: string format: date scheduledDate: type: string format: date description: >- Installment recognition anchor. When present, incurredDate for this invoice is this date and the invoice remains scheduled until it arrives. payeeId: type: string format: uuid description: Canonical Person, Organization, or Exposure entity billed or paid. memo: type: string lineItems: type: array minItems: 1 items: $ref: '#/components/schemas/PolicyInvoiceBatchCreateLine' PolicyInvoiceBatchCreateLine: type: object additionalProperties: false required: - label - amountCents properties: label: type: string minLength: 1 description: >- Line-item name on this invoice type: a line item the policy's stated billing names or, with invoicing enabled, one an existing kept invoice carries. amountCents: type: integer description: >- Signed integer cents in the configured line-item type's own frame. A negative amount reverses the line: a credit on the same line. memo: type: string responses: Unauthorized: description: Unauthorized - Invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missingApiKey: summary: Missing API key value: error: code: AuthenticationError message: API key authentication required userMessages: - API key authentication required invalidApiKey: summary: >- Invalid API key (e.g. unknown key, or a Bearer token used instead of an API key) value: error: code: AuthenticationError message: Invalid API key userMessages: - Invalid API key ForbiddenQuoteInvoicing: description: > Forbidden. The API key lacks the endpoint's permission, or policy invoicing is disabled for the company (`finv2-policy-invoicing-disabled`), including companies awaiting their billing migration. Nothing is saved. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invoicingDisabled: summary: Policy invoicing is disabled value: error: code: finv2-policy-invoicing-disabled message: >- Policy invoicing is not turned on for your company yet, so policy invoices cannot be created or changed. Contact support to enable it. userMessages: - >- Policy invoicing is not turned on for your company yet, so policy invoices cannot be created or changed. Contact support to enable it. insufficientPermissions: summary: Insufficient permissions value: error: code: AuthorizationError message: User is not authorized to perform the requested action userMessages: - User is not authorized to perform the requested action QuoteInvoicingClosed: description: >- The quote's invoicing can no longer change. A `bound` quote returns `QuoteBoundImmutable` with `referencingPolicy`, the policy it is bound to: that policy holds its invoices now, and the policy invoice batch changes them. A `cancelled` quote returns `QuoteNotEditable`. Nothing is saved. content: application/json: schema: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string enum: - QuoteBoundImmutable - QuoteNotEditable description: Machine-readable error code message: type: string description: Human-readable error message, naming why and the fix userMessages: type: array items: type: string referencingPolicy: type: string format: uuid nullable: true description: >- `QuoteBoundImmutable` only: the policy the quote is bound to. examples: quoteBound: summary: The quote is bound value: error: code: QuoteBoundImmutable message: >- Quote 550e8400-e29b-41d4-a716-446655440002 is bound to policy 550e8400-e29b-41d4-a716-446655440020, so its invoice settings and plan can no longer change. The policy holds its invoices now: change them with POST /api/v1/companies/{companyId}/financials/policies/{policyId}/invoices/batch. userMessages: - >- Quote 550e8400-e29b-41d4-a716-446655440002 is bound to policy 550e8400-e29b-41d4-a716-446655440020, so its invoice settings and plan can no longer change. The policy holds its invoices now: change them with POST /api/v1/companies/{companyId}/financials/policies/{policyId}/invoices/batch. referencingPolicy: 550e8400-e29b-41d4-a716-446655440020 quoteCancelled: summary: The quote is cancelled value: error: code: QuoteNotEditable message: >- Quote 550e8400-e29b-41d4-a716-446655440002 is cancelled, so its invoice settings and plan can no longer change. A cancelled quote is closed: to invoice a variation, create a new quote (POST /entities/quote, or Copy Quote in the app). userMessages: - >- Quote 550e8400-e29b-41d4-a716-446655440002 is cancelled, so its invoice settings and plan can no longer change. A cancelled quote is closed: to invoice a variation, create a new quote (POST /entities/quote, or Copy Quote in the app). InternalServerError: description: Internal Server Error - Unexpected error occurred content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internalError: summary: Unexpected server error value: error: code: UncaughtActionError message: Uncaught error occurred in userMessages: - An unexpected error occurred. Please try again later. securitySchemes: ApiKeyAuth: type: apiKey in: header name: Authorization description: >- API key authentication. Send your raw API key as the `Authorization` header value with NO scheme prefix — `Authorization: YOUR-API-KEY`. Do NOT prefix it with `Bearer ` or `ApiKey `, and do not use an `X-API-Key` header; those are not accepted. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.