Add/Update Credit


The following endpoint can be used to add or update a credit (a credit memo or credit note) within the Hyfin application. A credit is money owed to a customer. Once issued, the customer can apply it to their open invoices at checkout in the customer portal. Every amount is stored as a positive number.


Punto Final

The following endpoint can be used to add or update a credit. You must replace the {base_url} and {site_id} variables with the appropriate values. Credits are available on API version 4.0 only, and must be enabled for the site; a site without credits answers credits_not_enabled .

POST
{base_url}/api/v4/site/{site_id}/credit/addUpdate

  • A credit created through the API is issued immediately and can be applied right away.
  • Send every amount positive, or send your system's negative amounts with autoReverseAmount: true and they are flipped before they are stored. A negative amount without the flag, or the flag on a positive amount, is refused, so a sign is never changed by accident.
  • A line whose sign differs from the credit's (a charge inside a credit) is refused: net it into the credit or send it as an invoice.
  • Once a credit has been applied, its amount cannot be lowered below what has been applied, and its customer can never be changed.
  • Pass deleted: true to void a credit that has not been applied. A voided credit stays voided: posting it again is refused with credit_voided .
Solicitud
Campo
Tipo
Descripción
_id
String
El id del crédito. Este campo lo genera automáticamente el sistema y no es obligatorio al crear un nuevo crédito. Se requiere _id o externalId al actualizar un crédito existente.
externalId
String
El id único del crédito del sistema o base de datos de origen. Obligatorio al crear un crédito sin _id. Si detectamos un crédito con el mismo externalId, se actualizará; de lo contrario, se agregará. No puede coincidir con el externalId de una orden de compra en el mismo sitio.
creditNumber
String
El número de crédito que se muestra al cliente (el "N.º de crédito"). De forma predeterminada es el código.
kind
String
El tipo de crédito. Solo se puede crear creditNote a través de la API.
Default = creditNote | One of creditNote
customer
Una referencia al cliente al que pertenece el crédito. No se puede cambiar después de crear el crédito.
billToCustomer
El cliente a facturar, si es diferente al customer.
creditDate
La fecha del crédito. Una fecha sin hora. Si se envía una hora o zona horaria con ella, se descarta, no se convierte, por lo que la fecha permanece tal como se escribió. Format = YYYY-MM-DD
poNumber
String
El número de orden de compra del crédito.
description
String
Una descripción breve del crédito, como el motivo o la autorización de devolución.
customerMemo
String
Una nota para el cliente.
internalMemo
String
Una nota interna. Nunca se muestra al cliente.
lines
Las partidas del crédito. Se requiere al menos una partida, y el total de cada partida debe ser igual a su subtotal más su impuesto.
amount
Number
El valor nominal del crédito: subtotal + taxes - discounts. Se calcula a partir de las partidas si se omite. Este es un número entero de centavos, por lo que 1035 significa $10.35.
subtotal
Number
La suma de los subtotales de las partidas. Este es un número entero de centavos, por lo que 1035 significa $10.35.
taxes
Number
El impuesto del crédito. Este es un número entero de centavos, por lo que 1035 significa $10.35.
discounts
Number
Cualquier descuento del crédito, como un monto positivo. Este es un número entero de centavos, por lo que 1035 significa $10.35.
autoReverseAmount
Boolean
Establézcalo en true cuando su sistema almacene los créditos como montos negativos. Todos los montos se convierten a positivos antes de almacenarse. Se rechaza un monto negativo sin esta marca, o esta marca en un monto positivo.
Default = false
deleted
Boolean
Envíe true para anular el crédito. Un crédito que se ha aplicado a una orden de compra no se puede anular. Un crédito anulado no se puede actualizar ni volver a crear con el mismo id. El indicador permanece en false en el registro; status indica voided.
			
{
  "externalId": "CM-88123",
  "creditNumber": "CM-88123",
  "creditDate": "2026-10-01",
  "poNumber": "PO-552",
  "description": "Return RMA 7781",
  "customer": {
    "externalId": "100234"
  },
  "lines": [
    {
      "name": "Returned: Cabinet Knob K-12",
      "qty": 10,
      "unitPrice": 1250,
      "subtotal": 12500,
      "total": 12500
    },
    {
      "name": "Returned: Drawer Pull P-40",
      "qty": 2,
      "unitPrice": 1250,
      "subtotal": 2500,
      "total": 2500
    }
  ]
}


		
Respuesta
Campo
Tipo
Descripción
success
Boolean
Whether the record was added or updated successfully.
action
String
Informs whether the record was added or updated. Will only be returned if success is true.
One of added, updated
_id
String
The id we assign to the record.
updatedAt
The date the record was last updated. Un momento en el tiempo en formato ISO 8601, con zona horaria. Format = YYYY-MM-DDTHH:mm:ss.SSSZ
errors
String [ ]
A list of errors. Will only be returned if success is false.
			
{
  "success": true,
  "action": "added",
  "_id": "60f720d248f143332af022e0",
  "updatedAt": "2025-05-30T19:19:44.143Z"
}


		

Sending a credit through Add/Update Invoice

If your system stores credits as negative invoices, you can keep sending them to site/{site_id}/invoice/addUpdate (single or batch) and add isCredit: true . The record is stored as a credit instead of an invoice, and the response's recordType is credit . On a site with credits enabled, a negative invoice without isCredit is refused with negative_invoice_requires_is_credit .

  • invoiceNumber and invoiceDate become the credit number and credit date, and totals supplies the amounts.
  • Lines are optional here: a credit sent without lines gets one line built from its description and total, and the response warns line_synthesized .
  • Invoice-only fields such as send and dueDate are ignored and listed in warnings .
  • Payments, installments, fees and templates are refused on a credit.
  • A credit and an invoice on the same site cannot share an external id.
Solicitud de ejemplo
			
{
  "isCredit": true,
  "autoReverseAmount": true,
  "externalId": "CM-88123",
  "invoiceNumber": "CM-88123",
  "invoiceDate": "2026-10-01",
  "poNumber": "PO-552",
  "customer": {
    "externalId": "100234"
  },
  "description": "Return RMA 7781",
  "totals": {
    "subtotal": -15000,
    "taxes": 0,
    "discounts": 0,
    "total": -15000
  }
}


		
Respuesta de ejemplo
			
{
  "success": true,
  "action": "added",
  "_id": "6717a2c4e1f0a93b2c5d8e11",
  "updatedAt": "2026-10-01T14:02:37.000Z",
  "recordType": "credit",
  "code": "P5XU4MK7QZ2X",
  "warnings": [
    "line_synthesized"
  ]
}


		

How applied credits appear

Each application of a credit to an invoice is recorded as a payment with type: 'credit' and credit set to the credit's _id , so it reduces the invoice balance like any payment. Read it with the Payments endpoints and the payment webhook; a voided application reports status: 'voided' . These payments are read-only through the API.

Errors

A refused credit answers HTTP 422 with one of the following codes. A 422 is permanent: correct the payload rather than retrying it.

  • credits_not_enabled : credits are not enabled for the site.
  • credit_identity_required : a new credit needs an _id or externalId .
  • credit_lines_required : Add/Update Credit needs at least one line.
  • credit_negative_amount_requires_auto_reverse , credit_auto_reverse_on_non_negative_amount , credit_zero_amount : the amount's sign does not match autoReverseAmount , or the credit is zero.
  • credit_mixed_sign_lines : a line's sign differs from the credit's.
  • credit_totals_mismatch , credit_line_totals_mismatch : the amounts do not add up.
  • credit_identity_conflict : the external id belongs to another credit or to an invoice.
  • credit_customer_immutable , credit_amount_below_applied , credit_has_applications : the change is not allowed once the credit has been applied.
  • credit_voided : the credit is voided.
  • credit_kind_not_authorable : only creditNote can be created.