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

Atributos

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 string
Moneda de la Invoice. Si no se envía, se toma la de la Account de cobro. Determina cuántos decimales admite el monto.

Valores posibles: CLP, CLF, MXN, BRL, USD.

customer string
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
Fecha de vencimiento de la Invoice, en formato YYYY-MM-DD.

expiration_action string
Acción que se ejecuta sobre la Invoice cuando expira.

Valores posibles: EXPIRE, VOID, 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
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
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
Datos de la devolución asociada a la Invoice. Es nulo si la Invoice no tiene devoluciones.

refund_data.id_transaction_payment string

refund_data.id_transaction_refund string

refund_data.refund_amount number

refund_data.refund_reason string

refund_data.refund_status string
Resultado de la devolución asociada a una Invoice.

Valores posibles: success, failed.

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 string
Estado detallado de la Invoice, incluyendo si tiene un cobro en curso.

Valores posibles: 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.

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

Ejemplo

{
  "account": "acc_gzD0XoUTFxbUFcItpWOCqN686noSd9HQ",
  "amount": 19990,
  "currency_code": "CLP",
  "customer": "cus_ejC08yLqOWoFhVx4Fx42E3IR9X50tNx2",
  "disable_automatic_payment": false,
  "due_date": "2025-03-10",
  "expiration_action": "EXPIRE",
  "expiration_date": "2025-03-10T03:00:00Z",
  "id": "in_9K0bTq3xR7yA2sVpLmZ4wE1nHdJf6UcQ",
  "id_receipt": 0,
  "invoice_external_id": "F-2025-000123",
  "is_paid": false,
  "is_void": false,
  "link_payment": "https://portal.pagos.com/tu-empresa",
  "max_collection_attempts": 3,
  "metadata": {
    "sucursal": "Providencia"
  },
  "paid_amount": 0,
  "product_id": "plan-oro-marzo-2025",
  "receipt_type": "bill",
  "refund_data": {
    "id_transaction_payment": "string",
    "id_transaction_refund": "string",
    "refund_amount": 0,
    "refund_reason": "string",
    "refund_status": "success"
  },
  "remaining_collection_attempts": 3,
  "source": "integration_etl",
  "status": "UNPAID",
  "subscription": "sub_Y_EgOXMloD5-IJn6d9S2IxkNvp9p0iiP"
}