> ## 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. # Update an invoice > Updates the `metadata` of the invoice with the given `id`. This is the only attribute you can change, and you can change it at any point in the invoice's lifecycle, including after it is paid or voided. When `metadata` is provided, it replaces the entire existing metadata object. If you omit it, the invoice keeps its current metadata. The invoice must belong to your organization and to the `live` or `test` mode of the API key used. ## OpenAPI ````yaml reference/main-api.json PATCH /v2/invoices/{id} openapi: 3.1.0 info: title: fintoc-api version: v2026-02-01 servers: - url: https://api.fintoc.com security: [] paths: /v2/invoices/{id}: patch: tags: - Invoices summary: Update an invoice description: >- Updates the `metadata` of the invoice with the given `id`. This is the only attribute you can change, and you can change it at any point in the invoice's lifecycle, including after it is paid or voided. When `metadata` is provided, it replaces the entire existing metadata object. If you omit it, the invoice keeps its current metadata. The invoice must belong to your organization and to the `live` or `test` mode of the API key used. operationId: v2.invoices-update parameters: - name: id in: path description: Unique identifier of the invoice to update. required: true schema: type: string requestBody: content: application/json: schema: type: object properties: metadata: type: object example: order_id: '1234' description: >- Set of key-value pairs to attach to the invoice, useful for storing additional structured information. Up to 50 keys, with key names up to 40 characters and string values up to 500 characters. Sending `metadata` replaces the entire existing object. examples: update_invoice: summary: Update the metadata of an invoice value: metadata: order_id: '1234' responses: '200': description: The updated invoice, including its line items and payments. content: application/json: examples: invoice_updated: value: id: inv_2bVdWxLpzXq8RkNcM3JtUv9AhTe object: invoice attempt_count: 0 collection_method: charge_automatically created_at: '2026-05-01T12:00:00Z' currency: CLP customer: cus_2bVdWyTnGq4PfLs7DkXjRm0CwIo default_payment_method: pm_2bVdX3StMv9UkQxCIpCoWr5H1Nt hosted_invoice_url: >- https://acme.billing.fintoc.com/invoices/inv_2bVdWxLpzXq8RkNcM3JtUv9AhTe 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 metadata: order_id: '1234' mode: live next_payment_attempt_at: null payments: [] status: open subscription: sub_2bVdWzKfHr5QgMt8ElYkSn1DxJp total: 30000 schema: $ref: '#/components/schemas/invoice_v2' '400': description: The `metadata` violates its format rules. content: application/json: examples: invalid_metadata: value: error: type: invalid_request_error code: invalid_metadata param: metadata message: Array values not permitted in Metadata doc_url: https://docs.fintoc.com/reference/errors schema: $ref: '#/components/schemas/error_object_v2' '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 invoice: inv_fake_id' doc_url: https://docs.fintoc.com/reference/errors schema: $ref: '#/components/schemas/error_object_v2' security: - api_key: [] components: schemas: invoice_v2: type: object properties: id: type: - string - 'null' description: >- Unique identifier of the invoice. `null` on the preview invoice carried by an `invoice.upcoming` event, since Fintoc has not created that invoice yet. example: 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 collection_method: type: string enum: - charge_automatically - send_invoice description: >- The way Fintoc collects the invoice. `charge_automatically` means Fintoc charges `default_payment_method` once the invoice is finalized. `send_invoice` means Fintoc leaves the invoice open for you to collect, through `hosted_invoice_url` or outside Fintoc. Subscription invoices inherit the collection method when issued and keep that collection method even if the subscription changes later. example: send_invoice created_at: type: - string - 'null' format: date-time description: >- ISO 8601 timestamp of when the invoice was created. `null` on the preview invoice carried by an `invoice.upcoming` event, since that invoice does not exist yet. 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 external_payment: type: boolean description: >- Whether the invoice was settled with a payment collected outside Fintoc. `false` for invoices Fintoc collected, and for invoices that are not yet paid. example: false hosted_invoice_url: type: - string - 'null' description: >- URL of the hosted invoice page, where your customer can view and pay the invoice. `null` for invoices that are not `open`. In `test` mode, the URL points to the test mode portal. example: >- https://acme.billing.fintoc.com/invoices/inv_2bVdWxLpzXq8RkNcM3JtUv9AhTe lines: type: array description: Line items that make up the invoice total. items: $ref: '#/components/schemas/invoice_line_item' metadata: type: object description: >- Set of key-value pairs attached to the invoice. `{}` 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. Also `null` on the preview invoice carried by an `invoice.upcoming` event, where `lines[].period_start` marks the charge date. 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`. The preview invoice carried by an `invoice.upcoming` event reports `draft` and never appears when you list invoices. example: draft subscription: type: - string - 'null' description: >- `id` of the subscription the invoice belongs to. `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 - collection_method - created_at - currency - customer - default_payment_method - external_payment - lines - metadata - mode - next_payment_attempt_at - payments - status - subscription - total error_object_v2: 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 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 - 'null' description: >- Unique identifier of the line item. `null` on line items carried by an `invoice.upcoming` event, since the invoice they belong to does not exist yet. 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 ````