> ## Documentation Index > Fetch the complete documentation index at: https://docs.fintoc.com/llms.txt > Use this file to discover all available pages before exploring further. # Add invoice lines > Appends one or more line items to a draft invoice and recalculates the invoice total. The invoice must be in `draft` status and every line item must use the invoice currency. If any line item is invalid, the whole request fails and no line item is added. **`v2`** ยท Base URL `https://api.fintoc.com/v2` ## OpenAPI ````yaml reference/fintoc-api-v2.json POST /invoices/{id}/add_lines openapi: 3.1.0 info: title: fintoc-api-v2 version: v2026-02-01 servers: - url: https://api.fintoc.com/v2 security: [] paths: /invoices/{id}/add_lines: post: tags: - Invoices summary: Add invoice lines description: >- Appends one or more line items to a draft invoice and recalculates the invoice total. The invoice must be in `draft` status and every line item must use the invoice currency. If any line item is invalid, the whole request fails and no line item is added. operationId: invoices-add-lines parameters: - name: id in: path description: The `id` of the invoice to add line items to. required: true schema: type: string requestBody: content: application/json: schema: type: object properties: lines: type: array minItems: 1 description: >- Line items to append to the invoice. Must contain at least one line item. items: type: object properties: amount: type: integer example: 30000 description: >- Amount of the line item, in the smallest unit of `currency` (for example, `30000` for $30000 CLP, since CLP has no minor unit, or `3000` for $30.00 MXN). Must be greater than 0. currency: type: string enum: - CLP - MXN example: CLP description: >- Currency of the line item, as an ISO 4217 code. Must match the invoice currency. period_end: type: string format: date-time example: '2026-06-01T00:00:00Z' description: >- ISO 8601 datetime in UTC marking the end of the billing period covered by the line item. Optional, but must be provided together with `period_start` and be after it. Omit both for invoices not tied to a subscription. period_start: type: string format: date-time example: '2026-05-01T00:00:00Z' description: >- ISO 8601 datetime in UTC marking the start of the billing period covered by the line item. Optional, but must be provided together with `period_end`. Omit both for invoices not tied to a subscription. quantity: type: integer example: 1 description: >- Number of units billed by the line item. Must be greater than 0. name: type: string description: Display name for the line item shown on the invoice. example: Premium Plan description: type: string example: A premium plan description: >- Additional details about the line item shown on the invoice. required: - amount - currency - quantity - name required: - lines examples: add_lines: summary: Add a line item value: lines: - amount: 30000 currency: CLP period_end: '2026-06-01T00:00:00Z' period_start: '2026-05-01T00:00:00Z' quantity: 1 name: Premium Plan description: A premium plan responses: '200': description: >- The updated invoice, including the new line items and the recalculated total. content: application/json: examples: invoice_with_new_lines: value: id: inv_2bVdWxLpzXq8RkNcM3JtUv9AhTe object: invoice hosted_invoice_url: null created_at: '2026-05-01T12:00:00Z' currency: CLP customer: cus_2bVdWyTnGq4PfLs7DkXjRm0CwIo lines: - id: il_2bVdX0PqJs6RhNu9FmZlTo2EyKq object: line_item name: Premium Plan description: A premium plan amount: 30000 currency: CLP period_end: '2026-06-01T00:00:00Z' period_start: '2026-05-01T00:00:00Z' quantity: 1 - id: il_2bVdX1QrKt7SiOvAGnAmUp3FzLr object: line_item name: Premium Plan description: A premium plan amount: 20000 currency: CLP period_end: '2026-06-01T00:00:00Z' period_start: '2026-05-01T00:00:00Z' quantity: 2 metadata: null mode: live payments: [] status: draft subscription: sub_2bVdWzKfHr5QgMt8ElYkSn1DxJp total: 50000 schema: $ref: '#/components/schemas/invoice' '400': description: >- Invalid request. The request has one of these issues: missing `lines`, invalid `amount` or `quantity`, a currency mismatch, or a malformed date. It can also return when exactly one of `period_start` and `period_end` is provided, or when `period_end` is not after `period_start`. content: application/json: examples: invalid_currency: value: error: type: invalid_request_error code: invalid_currency message: 'Invalid currency: XYZ' invalid_period: value: error: type: invalid_request_error code: invalid_period message: period_end must be greater than period_start schema: $ref: '#/components/schemas/error_object' '401': description: Invalid or missing API key. content: application/json: examples: invalid_api_key: value: error: type: authentication_error code: invalid_api_key message: 'Invalid API Key: invalid-*oken' schema: $ref: '#/components/schemas/error_object' '404': description: >- The invoice does not exist, belongs to another organization, or belongs to a different mode than the API key. content: application/json: examples: invoice_not_found: value: error: type: invalid_request_error code: missing_resource param: id message: 'No such invoicing/invoice: inv_fake' doc_url: https://docs.fintoc.com/reference/errors schema: $ref: '#/components/schemas/error_object' '409': description: >- The invoice is not editable: line items can only be added while the invoice is in `draft` status. content: application/json: examples: invoice_not_editable: value: error: type: invalid_request_error code: invoice_not_editable message: Invoice may only be edited when in draft status schema: $ref: '#/components/schemas/error_object' security: - api_key: [] components: schemas: invoice: type: object properties: id: type: string description: Unique identifier of the invoice. example: inv_2bVdWxLpzXq8RkNcM3JtUv9AhTe hosted_invoice_url: type: - string - 'null' description: >- URL of the hosted invoice page, where your customer can view and pay the invoice. `null` for `test` mode invoices and for invoices that are not `open`. example: >- https://acme.billing.fintoc.com/invoices/inv_2bVdWxLpzXq8RkNcM3JtUv9AhTe object: const: invoice description: Type of the object. Always `invoice`. attempt_count: type: integer description: >- Number of automatic charge attempts Fintoc has made on the invoice. `0` until the invoice is finalized and charged for the first time. example: 1 created_at: type: string format: date-time description: ISO 8601 timestamp of when the invoice was created. example: '2026-05-01T12:00:00Z' currency: type: string enum: - CLP - MXN description: >- Currency of the invoice, as an ISO 4217 code. Every line item uses this currency. example: CLP customer: type: string description: '`id` of the customer the invoice bills.' example: cus_2bVdWyTnGq4PfLs7DkXjRm0CwIo default_payment_method: type: - string - 'null' description: >- `id` of the payment method Fintoc charges when the invoice is finalized. `null` for invoices without one, such as subscription invoices. example: pm_2c4mDhAbCdEfGhIjKlMnOpQrStu lines: type: array description: Line items that make up the invoice total. items: $ref: '#/components/schemas/invoice_line_item' metadata: type: - object - 'null' description: >- Set of key-value pairs attached to the invoice. `null` when the invoice has no metadata. mode: type: string enum: - live - test description: >- Mode of the invoice. `live` invoices use real data; `test` invoices use fake data for integration testing. An API key only sees invoices that share its mode. example: live next_payment_attempt_at: type: - string - 'null' format: date-time description: >- ISO 8601 timestamp of the next scheduled automatic charge attempt. `null` when no further attempt is scheduled. example: '2026-05-02T12:00:00Z' payments: type: array description: Payment attempts to collect the invoice. items: type: object properties: amount: type: integer description: >- Amount of the payment, in the smallest unit of `currency` (for example, `30000` for $30000 CLP, since CLP has no minor unit, or `3000` for $30.00 MXN). example: 30000 currency: type: string enum: - CLP - MXN description: >- Currency of the payment, as an ISO 4217 code. Always matches the invoice currency. example: CLP payment_intent: type: string description: '`id` of the payment intent created to collect the invoice.' example: pi_2bVdX2RsLu8TjPwBHoBnVq4G0Ms status: type: string enum: - pending - succeeded - failed description: Status of the payment attempt. example: succeeded required: - amount - currency - payment_intent - status status: type: string enum: - draft - open - paid - void description: >- Status of the invoice. Invoices start as `draft`, become `open` when finalized, and end as `paid` or `void`. example: draft subscription: type: - string - 'null' description: >- `id` of the subscription that generated the invoice. `null` for invoices not tied to a subscription. example: sub_2bVdWzKfHr5QgMt8ElYkSn1DxJp total: type: integer description: >- Total amount of the invoice, in the smallest unit of `currency` (for example, `30000` for $30000 CLP, since CLP has no minor unit, or `3000` for $30.00 MXN). Equals the sum of the line item amounts. example: 30000 required: - id - hosted_invoice_url - object - attempt_count - created_at - currency - customer - default_payment_method - lines - metadata - mode - next_payment_attempt_at - payments - status - subscription - total error_object: type: object properties: error: type: object description: Details of the error that caused the request to fail. properties: code: type: string description: >- Machine-readable code identifying the specific error, for example `invalid_api_key`. Not returned by every error. example: invalid_api_key doc_url: type: string description: >- URL of a documentation page with more details about the error. Not returned by every error. example: https://docs.fintoc.com/reference/errors message: type: string description: Human-readable message describing the error. example: 'Invalid API Key: invalid-*oken' param: type: - string - 'null' description: >- Name of the request parameter that caused the error. `null` when the error cannot be tied to a single parameter, and not returned by every error. example: amount type: type: string description: >- Category of the error, for example `invalid_request_error`, `authentication_error`, or `api_error`. example: invalid_request_error required: - type - message invoice_line_item: type: object properties: id: type: string description: Unique identifier of the line item. example: il_2bVdX0PqJs6RhNu9FmZlTo2EyKq object: const: line_item description: Type of the object. Always `line_item`. amount: type: integer description: >- Amount of the line item, in the smallest unit of `currency` (for example, `30000` for $30000 CLP, since CLP has no minor unit, or `3000` for $30.00 MXN). example: 30000 currency: type: string enum: - CLP - MXN description: >- Currency of the line item, as an ISO 4217 code. Always matches the invoice currency. example: CLP description: type: - string - 'null' description: >- Additional details about the line item shown on the invoice. `null` when the line item has no description. example: A premium plan name: type: string description: Display name for the line item shown on the invoice. example: Premium Plan period_end: type: - string - 'null' format: date-time description: >- ISO 8601 datetime in UTC marking the end of the billing period covered by the line item. `null` for line items on invoices not tied to a subscription. example: '2026-06-01T00:00:00Z' period_start: type: - string - 'null' format: date-time description: >- ISO 8601 datetime in UTC marking the start of the billing period covered by the line item. `null` for line items on invoices not tied to a subscription. example: '2026-05-01T00:00:00Z' quantity: type: integer description: Number of units billed by the line item. example: 1 required: - id - object - name - description - amount - currency - period_end - period_start - quantity securitySchemes: api_key: type: apiKey name: Authorization in: header ````