---
title: "Editar Invoice"
method: PUT
path: "/invoices/{encrypted_invoice_id}"
tags: ["Invoices"]
---

# Editar Invoice

`PUT /invoices/{encrypted_invoice_id}`

## Request

- Base URL: `https://api.trytoku.com`
- URL: `https://api.trytoku.com/invoices/{encrypted_invoice_id}`
- Auth: API key in header `x-api-key`

Actualiza los datos de una Invoice existente.

Solo modifica los campos presentes en el cuerpo; los omitidos se mantienen sin cambios. Devuelve la Invoice ya actualizada y responde `404` si no existe bajo la organización y Account autenticadas.

**Límite de tasa:** 20 solicitudes por segundo. Al superarlo, la API responde `429`. Ver [Límites de tasa](/reference/limites-de-tasa).

## Path parameters

- `encrypted_invoice_id` string, required: Identificador público de la Invoice a editar (`in_...`).

## Headers

- `x-account-key` string: Llave de API de una Account, para operar sobre esa Account en lugar de la principal.
- `x-api-version` string, date: Versión del API para esta petición, como cualquier fecha `YYYY-MM-DD`. Fija el contrato de la respuesta; si se omite, se deriva de la fecha de creación de la organización.

## Request body

- UpdateInvoicePayload: Campos del cuerpo para actualizar una Invoice.
  - `amount` number: Monto de la Invoice, expresado en la moneda indicada en `currency_code`. La cantidad de decimales admitida la define la moneda: CLP no acepta decimales, MXN y BRL aceptan 2, y CLF acepta 4. Debe ser menor que 1.000.000.000.000.000 (10^15).
  - `currency_code` 'CLP' | 'CLF' | 'MXN' | 'BRL' | 'USD': Moneda, en código [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html). Cubre las monedas de los países donde Toku opera —`CLP` (peso chileno), `MXN` (peso mexicano) y `BRL` (real)— más `USD` y `CLF`, la Unidad de Fomento chilena. La moneda determina cuántos decimales admiten los montos: `CLP` no admite decimales, `MXN`, `BRL` y `USD` admiten dos, y `CLF` cuatro.
  - `customer` string: Identificador público del Customer (`cus_...`) dueño de la Invoice.
  - `disable_automatic_payment` boolean: Excluye la Invoice del cobro automático. Permite cargarla sin que se mande a cobrar aunque el Customer tenga un método de pago automático activo.
  - `due_date` string: Fecha de vencimiento de la Invoice, en formato `YYYY-MM-DD`.
  - `expiration_action` union: Acción que se ejecuta sobre la Invoice cuando expira. Se envía un string vacío para dejarla sin acción de expiración.
    - 'EXPIRE' | 'VOID' | 'DELETE': Acción que se ejecuta sobre una Invoice cuando expira: marcarla como expirada (`EXPIRE`), anularla (`VOID`) o eliminarla (`DELETE`). `EXPIRE` es legado: se mantiene por compatibilidad, pero deja la Invoice en el estado `EXPIRED`, que está deprecado. Para nuevas integraciones usa `VOID` o `DELETE`.
    - string
  - `expiration_date` string: Fecha y hora de expiración de la Invoice; a partir de ese momento no se realizan más intentos de cobro. Se acepta `YYYY-MM-DD HH:MM:SS` (hora local de la organización) o una fecha ISO 8601 con zona horaria explícita.
  - `id_receipt` integer: Identificador del recibo asociado a la Invoice.
  - `invoice_external_id` string: Identificador único de la deuda externo a Toku. Permite distinguir dos Invoices del mismo producto que vencen el mismo día.
  - `is_paid` boolean: Marca la Invoice como pagada: registra un pago externo por el monto total de la Invoice. Al editar una Invoice ya pagada, enviarlo en `false` elimina el pago registrado y la deja no pagada; no se puede desmarcar si el pago lo cobró Toku.
  - `is_void` boolean: Indica si la Invoice está anulada.
  - `link_payment` string: URL donde se debe pagar la Invoice. Se deja vacía para usar el portal de pagos de Toku; se completa solo si se desea utilizar un procesador de pagos externo.
  - `max_collection_attempts` union: Cantidad máxima de intentos de cobro antes de que la Invoice expire. Se envía un string vacío para quitar el límite.
    - integer
    - string
  - `metadata` object: Valores adicionales definidos por la organización. Se tratan como texto y no pueden superar los 256 caracteres cada uno. Deben declararse en la webapp de Toku antes de poder usarse.
  - `payment_amount` number: Monto del pago externo a registrar cuando la misma solicitud marca la Invoice como pagada con `is_paid: true`; si se omite, el pago se registra por el total de la Invoice. Su caso de uso habitual es una Invoice expresada en UF (`CLF`) que se cobra en pesos: sirve para dejar registrado el monto efectivamente cobrado en la moneda del cobro. No fija el monto pagado de la Invoice (`paid_amount`): ese valor lo calcula Toku a partir de los pagos registrados, así que enviar `payment_amount` sin `is_paid: true` se rechaza con `422`. Para registrar un pago parcial se usa [`POST /external-transactions`](/reference/create_external_transaction). Debe ser mayor que `0` y menor que 1.000.000.000.000.000 (10^15).
  - `product_id` string: Identificador del producto de la organización asociado a la Invoice.
  - `receipt_type` 'bill' | 'invoice' | 'no_receipt': Documento tributario que se emite al cobrar: `bill` es una boleta, `invoice` una factura y `no_receipt` deja el cobro sin documento asociado.
  - `source` string: Origen desde el que se creó la Invoice. Se informa cuando la carga proviene de una integración o de un proceso interno; en una creación por API se deja vacío.
  - `subscription` string: Identificador público de la Subscription (`sub_...`) a la que pertenece la Invoice.

## Response `200`

Invoice ya actualizada.

- Invoice: Deuda de un Customer: el monto que se le cobra, en qué estado de pago está y con qué datos se cobra. Toda Invoice cuelga de un Customer y de una Subscription. La Subscription se indica por su identificador, si ya existe, o por el `product_id` del producto que la genera; en ese caso Toku la crea junto con la Invoice. Dentro de una misma Subscription el `invoice_external_id` no se repite: es la clave con la que Toku decide si crea una Invoice nueva o actualiza la que ya existía.
  - `account` string: Identificador público de la Account de cobro a la que pertenece la Invoice.
  - `amount` number: Monto adeudado, expresado en la moneda indicada en `currency_code`. La cantidad de decimales admitida la define la moneda: CLP no acepta decimales, MXN y BRL aceptan 2, y CLF acepta 4.
  - `currency_code` 'CLP' | 'CLF' | 'MXN' | 'BRL' | 'USD': Moneda, en código [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html). Cubre las monedas de los países donde Toku opera —`CLP` (peso chileno), `MXN` (peso mexicano) y `BRL` (real)— más `USD` y `CLF`, la Unidad de Fomento chilena. La moneda determina cuántos decimales admiten los montos: `CLP` no admite decimales, `MXN`, `BRL` y `USD` admiten dos, y `CLF` cuatro.
  - `customer` string, required: Identificador público del Customer dueño de la Invoice.
  - `disable_automatic_payment` boolean: Indica si la Invoice está excluida del cobro automático. Permite cargarla sin que se mande a cobrar aunque el Customer tenga un método de pago automático activo.
  - `due_date` string, required: Fecha de vencimiento de la Invoice, en formato `YYYY-MM-DD`.
  - `expiration_action` 'EXPIRE' | 'VOID' | 'DELETE': Acción que se ejecuta sobre una Invoice cuando expira: marcarla como expirada (`EXPIRE`), anularla (`VOID`) o eliminarla (`DELETE`). `EXPIRE` es legado: se mantiene por compatibilidad, pero deja la Invoice en el estado `EXPIRED`, que está deprecado. Para nuevas integraciones usa `VOID` o `DELETE`.
  - `expiration_date` string, date-time: Fecha y hora de expiración de la Invoice. A partir de ese momento no se realizan más intentos de cobro.
  - `id` string, required: Identificador público de la Invoice.
  - `id_receipt` integer: Identificador del recibo asociado a la Invoice.
  - `invoice_external_id` string: Identificador único de la deuda externo a Toku. Permite distinguir dos Invoices del mismo producto que vencen el mismo día.
  - `is_paid` boolean: Indica si la Invoice está pagada.
  - `is_void` boolean: Indica si la Invoice está anulada. Las Invoices anuladas se tratan como si hubiesen sido borradas.
  - `link_payment` string: URL donde se debe pagar la Invoice. Se deja vacía para usar el portal de pagos de Toku; se completa solo si se desea utilizar un procesador de pagos externo.
  - `max_collection_attempts` integer: Cantidad máxima de intentos de cobro antes de que la Invoice expire.
  - `metadata` object: Valores adicionales definidos por la organización. Se tratan como texto y no pueden superar los 256 caracteres cada uno. Deben declararse en la webapp de Toku antes de poder usarse.
  - `paid_amount` number: Monto ya pagado de la Invoice. Se usa para reflejar pagos parciales.
  - `product_id` string, required: Identificador interno del producto que genera la Invoice. Puede ser un número de contrato o de propuesta.
  - `receipt_type` string: Tipo de recibo a emitir para la Invoice: `bill` (boleta), `invoice` (factura) o `no_receipt` (sin recibo).
  - `refund_data` RefundData
    - `id_transaction_payment` string, required
    - `id_transaction_refund` string, required
    - `refund_amount` number, required
    - `refund_reason` string, required
    - `refund_status` 'success' | 'failed', required: Resultado de la devolución asociada a una Invoice.
  - `remaining_collection_attempts` integer: Intentos de cobro que quedan disponibles. Se reinicia por completo si cambia `max_collection_attempts`.
  - `source` string: Origen desde el que se creó la Invoice, por ejemplo una carga masiva, una integración o una Subscription recurrente. Es nulo cuando no se informó al crearla.
  - `status` 'DELETED' | 'VOID' | 'UNPAID' | 'PAID' | 'PARTIALLY_PAID' | 'EXTERNALLY_PAID' | 'UNPAID_PAYMENT_IN_PROGRESS' | 'PARTIALLY_PAID_PAYMENT_IN_PROGRESS' | 'UNPAID_NON_BLOCKING_PAYMENT_IN_PROGRESS' | 'PARTIALLY_PAID_NON_BLOCKING_PAYMENT_IN_PROGRESS' | 'UNPAID_PARTIAL_PAYMENT_IN_PROGRESS' | 'PARTIALLY_PAID_PARTIAL_PAYMENT_IN_PROGRESS' | 'EXPIRED', required: Estado detallado de una Invoice. Combina el avance del pago (sin pagar, parcialmente pagada, pagada) con la existencia de un cobro en curso, y cubre además los estados terminales de anulación y eliminación. `EXPIRED` está deprecado: solo lo alcanzan las Invoices con acción de expiración `EXPIRE`.
  - `subscription` string, required: Identificador público de la Subscription a la que pertenece la Invoice.

## Other responses

- `401`: Falta de credenciales.
- `403`: Falta de permisos. No tienes por qué estar ahi 👀.
- `404`: El recurso no fue encontrado.
- `422`: El cuerpo de la petición no pasó la validación.
- `429`: Superaste el número máximos de request permitidos, espera un poquito.

---

[API](https://skmtc.dev/trytoku/apis/toku-api.md) - [All operations](https://skmtc.dev/trytoku/apis/toku-api/llms.txt) - [OpenAPI document](https://skmtc.dev/trytoku/apis/toku-api/revisions/a6ef070075b1?raw)