> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onepay.la/llms.txt
> Use this file to discover all available pages before exploring further.

# Emitir nota crédito

> Anula o devuelve, total o parcialmente, una factura ya timbrada.

Una nota crédito no es otra factura: es otro documento fiscal sobre la misma venta, con su propia numeración y apuntando a la factura que corrige. Por eso una factura puede tener varias, una por cada devolución.

<Note>
  Si reembolsas un cobro desde OnePay, la nota crédito se emite sola. Este endpoint es para los casos que no pasan por un reembolso: un error en la factura, una anulación acordada, una devolución que gestionas por fuera.
</Note>

<Warning>
  Necesitas una resolución de la DIAN con `document_type: "credit_note"` y su propio prefijo. Las notas llevan numeración aparte de las facturas.
</Warning>

### Headers

<ParamField header="x-idempotency" type="string" required placeholder="Token único para garantizar la idempotencia de la petición">
  Token único para garantizar la idempotencia de la petición
</ParamField>

### Body

<ParamField body="amount" type="integer" placeholder="15000000">
  Monto a devolver **en centavos**. Omítelo para anular la factura completa.

  OnePay no deja que la suma de las notas emitidas supere el total de la factura: sin ese tope, dos devoluciones parciales podrían descontar más IVA del que declaraste.
</ParamField>

<ParamField body="reason" type="string" placeholder="Instalación no realizada">
  Motivo de la nota. Hasta 500 caracteres. Queda guardado en el documento.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.onepay.la/v1/invoices/inv_01J8XK9V4N/credit-notes \
    -H "Authorization: Bearer $ONEPAY_API_KEY" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: 3b1c9d2e-7f4a-4c8b-9e1d-5a2f8c3b7e01" \
    -d '{
      "amount": 15000000,
      "reason": "Instalación no realizada"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={null}
  {
    "id": "stm_01J8XKB2R7",
    "type": "credit_note",
    "status": "accepted",
    "number": "NC900",
    "cufe": "d7b2f4a9...",
    "xml_url": "https://...",
    "pdf_url": "https://...",
    "replaces_id": "stm_01J8XKA1Q3",
    "total": 15000000,
    "currency": "COP",
    "stamped_at": "2026-08-05T10:14:02+00:00"
  }
  ```

  ```json 422 theme={null}
  {
    "code": "credit_note_not_issuable",
    "message": "La nota crédito por 15000000 excede lo que queda por devolver de la factura: total 28548100, ya devuelto 20000000, disponible 8548100."
  }
  ```
</ResponseExample>