Adjustment Documents4

Auth1

Batch Enrollment1

Beneficiaries3

Beneficiary Accounts3

Boleto4

Campaigns9

Checkout Session5

Consulta de consentimientos1

Customer Collection Accounts3

Customer Portal10

Customers8

Débito Automático1

Debt Reconciliation Public1

Downloads2

Efectivo2

Electronic Signature2

Embed Tokens1

Facturación14

Forum9

Funding Account1

Intents de consentimiento1

Invoices9

PAC2

Payment Flows1

Payment Intents4

Payment Methods15

Payments9

Payout1

Payout Request Ingestion1

Payout Request Items1

Pix2

Pix Automático5

PlanOk3

POS Terminals5

Preauthorizations1

puntored5

Receipts2

Refunds3

Rendition Files2

Reports9

Risk flow validator executions1

Sequences1

Sin catalogar6

Subscriptions8

Transactions13

Transferencias 🇨🇱1

Transferencias 🇲🇽10

Validación de Cuenta Clabe4

Webhook Endpoints4

Webhooks1

Invoices

Crear Invoice

Changed on Nov 3, 2026

Crea una Invoice o actualiza la existente si coincide el identificador.

Es la forma de cargar una Invoice a un Customer. Toda Invoice queda asociada a una Subscription: puedes indicarla por su identificador público si ya existe, o enviar un product_id y dejar que Toku resuelva la Subscription a partir de él. Es idempotente por su identificador de negocio (product_id más due_date o invoice_external_id): si la Invoice ya existe se actualiza y la respuesta es 200; si es nueva se crea y la respuesta es 201. El monto va en la moneda de la Invoice, con los decimales que esa moneda admita.

Límite de tasa: 20 solicitudes por segundo. Al superarlo, la API responde 429. Ver Límites de tasa.

post/invoices

Request

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

Headers

x-account-keystring

Llave de API de una Account, para operar sobre esa Account en lugar de la principal.

x-api-versionstring 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.

Example:2026-10-08

Request body

amountnumber

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

customerstring required

Identificador público del Customer (cus_...) dueño de la Invoice.

disable_automatic_paymentboolean

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_datestring required

Fecha de vencimiento de la Invoice, en formato YYYY-MM-DD.

expiration_datestring

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_receiptinteger

Identificador del recibo asociado a la Invoice.

invoice_external_idstring

Identificador único de la deuda externo a Toku. Permite distinguir dos Invoices del mismo producto que vencen el mismo día.

is_paidboolean

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_voidboolean

Indica si la Invoice está anulada.

link_paymentstring

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.

metadataobject

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.

product_idstring

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.

sourcestring

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.

subscriptionstring

Identificador público de la Subscription (sub_...) a la que pertenece la Invoice.

Example request

{
  "amount": 19990,
  "customer": "cus_ejC08yLqOWoFhVx4Fx42E3IR9X50tNx2",
  "due_date": "2025-03-10",
  "expiration_date": "2025-03-10 00:00:00",
  "invoice_external_id": "F-2025-000123",
  "link_payment": "https://portal.pagos.com/tu-empresa",
  "metadata": {
    "sucursal": "Providencia"
  },
  "product_id": "plan-oro-marzo-2025",
  "subscription": "sub_Y_EgOXMloD5-IJn6d9S2IxkNvp9p0iiP"
}

Response

Invoice actualizada (ya existía una con el mismo identificador).

accountstring

Identificador público de la Account de cobro a la que pertenece la Invoice.

amountnumber

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'

customerstring required

Identificador público del Customer dueño de la Invoice.

disable_automatic_paymentboolean

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_datestring 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_datestring date-time

Fecha y hora de expiración de la Invoice. A partir de ese momento no se realizan más intentos de cobro.

idstring required

Identificador público de la Invoice.

id_receiptinteger

Identificador del recibo asociado a la Invoice.

invoice_external_idstring

Identificador único de la deuda externo a Toku. Permite distinguir dos Invoices del mismo producto que vencen el mismo día.

is_paidboolean

Indica si la Invoice está pagada.

is_voidboolean

Indica si la Invoice está anulada. Las Invoices anuladas se tratan como si hubiesen sido borradas.

link_paymentstring

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_attemptsinteger

Cantidad máxima de intentos de cobro antes de que la Invoice expire.

metadataobject

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_amountnumber

Monto ya pagado de la Invoice. Se usa para reflejar pagos parciales.

product_idstring required

Identificador interno del producto que genera la Invoice. Puede ser un número de contrato o de propuesta.

receipt_typestring

Tipo de recibo a emitir para la Invoice: bill (boleta), invoice (factura) o no_receipt (sin recibo).

remaining_collection_attemptsinteger

Intentos de cobro que quedan disponibles. Se reinicia por completo si cambia max_collection_attempts.

sourcestring

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.

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.

subscriptionstring required

Identificador público de la Subscription a la que pertenece la Invoice.

Example response

{
  "account": "acc_gzD0XoUTFxbUFcItpWOCqN686noSd9HQ",
  "amount": 19990,
  "customer": "cus_ejC08yLqOWoFhVx4Fx42E3IR9X50tNx2",
  "due_date": "2025-03-10",
  "expiration_date": "2025-03-10T03:00:00Z",
  "id": "in_9K0bTq3xR7yA2sVpLmZ4wE1nHdJf6UcQ",
  "invoice_external_id": "F-2025-000123",
  "link_payment": "https://portal.pagos.com/tu-empresa",
  "max_collection_attempts": 3,
  "metadata": {
    "sucursal": "Providencia"
  },
  "product_id": "plan-oro-marzo-2025",
  "receipt_type": "bill",
  "remaining_collection_attempts": 3,
  "source": "integration_etl",
  "subscription": "sub_Y_EgOXMloD5-IJn6d9S2IxkNvp9p0iiP"
}

Changes

Nov 3, 2026a6ef070075b1 Revision changes
- breaking
  request body became required
- breaking
  for the header request parameter x-account-key, default value was added
- breaking
  added to the request property allOf list
- breaking
  added to the request property allOf list
- breaking
  removed the enum value DELETE of the request property
- breaking
  removed the enum value VOID of the request property
- breaking
  request property list-of-types was narrowed by removing types number from media type application/json
- breaking
  added the pattern ^((https://)|(http://))[a-zA-Z0-9.\-_~+#,%&=*;:@!/()?_{}\[\]|~]+$ to the request property link_payment
- breaking
  added the pattern ^(?:[^ \n](?:[^\n]*[^ \n])?)?$ to the request property
- breaking
  added the pattern ^\S+$ to the request property
- breaking
  the request property type changed from string to no type
- breaking
  the request property type changed from string to no type
- breaking
  the request property type changed from string to integer
- breaking
  the request property type changed from string to object, and format from json to no format
- breaking
  the request property type changed from string to no type
- breaking
  the response's property type changed from integer to number for status
- breaking
  the response's property type changed from integer to number for status
- breaking
  the response's property type changed from string to no type for status
- breaking
  the response's property type changed from string to no type for status
- breaking
  the response's property type changed from no type to integer for status
- breaking
  the response's property type changed from no type to integer for status
- breaking
  the response's property type changed from no type to string for status
- breaking
  the response's property type changed from no type to string for status
- breaking
  the response's property type changed from no type to string for status
- breaking
  the response's property type changed from no type to string for status
- breaking
  the response's property type changed from string to no type for status
- warning
  the request property's exclusiveMaximum was set to 1000000000000000.00
- warning
  the request property's maxLength was set to 256
- warning
  the request property's maxLength was set to 256
- warning
  the request property's maxLength was set to 256
- warning
  the request property's min was set to 0.00
- warning
  removed the optional property from the response with the status
- warning
  removed the optional property / from the response with the status
- warning
  removed the optional property / from the response with the status
- warning
  removed the optional property / from the response with the status
- warning
  removed the optional property / from the response with the status
- warning
  removed the optional property / from the response with the status
- warning
  removed the optional property / from the response with the status
- info
  api operation id crear-invoice removed and replaced with create_or_update_invoice
- info
  api tag Invoices added
- info
  added the new optional header request parameter x-api-version
- info
  added the new optional request property
- info
  added subschema #2 to the request property anyOf list
- info
  the request property became optional
- info
  the request property default value {} was added
- info
  the request property format was generalized from float to no format
- info
  the request property format was generalized from date to no format
- info
  the request property format was generalized from date-time to no format
- info
  added the non-success response with the status
- info
  added the non-success response with the status
- info
  added the non-success response with the status
- info
  removed the non-success response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added to the response property allOf list for the response status
- info
  added to the response property allOf list for the response status
- info
  added to the response property allOf list for the response status
- info
  the response property became required for the status
- info
  the response property became required for the status
- info
  the response property became required for the status
- info
  the response property became required for the status
- info
  the response property became required for the status
- info
  the response property / became required for the status
- info
  the response property / became required for the status
- info
  the response property became required for the status
- info
  the response property became required for the status
- info
  the response property became required for the status
- info
  the response property became required for the status
- info
  the response property became required for the status
- info
  the response property became required for the status
- info
  the response property became required for the status
- info
  the response's property default value changed from true to false for the status
- info
  the response's property default value changed from true to false for the status
- info
  the response's property default value changed from true to false for the status
- info
  the response's property default value changed from true to false for the status
- info
  the response's property default value changed from true to false for the status
- info
  the response's property default value changed from true to false for the status
- info
  the response's property default value 0 was removed for the status
- info
  the response's property default value 0 was removed for the status
- info
  added the required property to the response with the status
- info
  added the required property to the response with the status
- info
  added the required property to the response with the status

Operation history