---
title: "Anular Invoice"
method: POST
path: "/invoices/{encrypted_invoice_id}/void"
tags: ["Invoices"]
---

# Anular Invoice

`POST /invoices/{encrypted_invoice_id}/void`

## Request

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

Anula una Invoice para dejar de cobrarla.

Detiene los cobros de la Invoice y la marca como anulada. Por defecto, además la elimina; envía `delete_invoice=false` para conservarla anulada como registro histórico. La `metadata` que se envíe se combina con la que la Invoice ya tenía, en la misma operación que la anulación. Responde `404` si la Invoice 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 anular (`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

- VoidInvoicePayload: Campos del cuerpo para anular una Invoice.
  - `delete_invoice` boolean, required: Si es `true` (valor por defecto cuando se omite el cuerpo), además de anular la Invoice se elimina. Envía `false` para conservarla anulada como registro histórico.
  - `metadata` object: Valores adicionales a guardar en la Invoice al anularla, útiles para dejar registrado por qué se anuló. Se combinan con la metadata existente: las claves enviadas se agregan o reemplazan y las demás se conservan. Se tratan como texto y no pueden superar los 256 caracteres cada uno.

## Response `200`

Invoice anulada.

- 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)