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.


Point de terminaison

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 .
Demande
Champ
Type
Description
_id
String
L'identifiant du crédit. Ce champ est généré automatiquement par le système et n'est pas requis lors de la création d'un nouveau crédit. Soit _id, soit externalId est requis lors de la mise à jour d'un crédit existant.
externalId
String
L'identifiant unique du crédit provenant du système ou de la base de données source. Requis lors de la création d'un crédit sans _id. Si nous détectons un crédit avec le même externalId, il sera mis à jour; sinon, il sera ajouté. Il ne peut pas correspondre au externalId d'une Facture sur le même site.
creditNumber
String
Le numéro de crédit affiché au client (le « N° de crédit »). Par défaut, il correspond au code.
kind
String
Le type de crédit. Seul creditNote peut être créé par l'API.
Default = creditNote | One of creditNote
customer
Une référence au client auquel appartient le crédit. Elle ne peut pas être modifiée après la création du crédit.
billToCustomer
Le client à facturer, si différent du customer.
creditDate
La date du crédit. Une date sans heure. Une heure ou un fuseau horaire envoyé avec elle est ignoré, et non converti, de sorte que la date reste telle qu'écrite. Format = YYYY-MM-DD
poNumber
String
Le numéro de bon de commande du crédit.
description
String
Une brève description du crédit, comme le motif ou l'autorisation de retour.
customerMemo
String
Une note au client.
internalMemo
String
Une note interne. Elle n'est jamais affichée au client.
lines
Les lignes du crédit. Au moins une ligne est requise, et le total de chaque ligne doit être égal à son subtotal plus sa taxe.
amount
Number
La valeur nominale du crédit : subtotal + taxes - discounts. Calculée à partir des lignes si elle est omise. Il s'agit d'un nombre entier de cents, donc 1035 signifie $10.35.
subtotal
Number
La somme des sous-totaux des lignes. Il s'agit d'un nombre entier de cents, donc 1035 signifie $10.35.
taxes
Number
La taxe sur le crédit. Il s'agit d'un nombre entier de cents, donc 1035 signifie $10.35.
discounts
Number
Tout rabais sur le crédit, sous forme de montant positif. Il s'agit d'un nombre entier de cents, donc 1035 signifie $10.35.
autoReverseAmount
Boolean
Définissez à true lorsque votre système stocke les crédits sous forme de montants négatifs. Chaque montant est converti en positif avant d'être stocké. Un montant négatif sans cet indicateur, ou cet indicateur sur un montant positif, est refusé.
Default = false
deleted
Boolean
Passez true pour annuler le crédit. Un crédit qui a été appliqué à une facture ne peut pas être annulé. Un crédit annulé ne peut pas être mis à jour ni recréé sous le même id. L'indicateur reste false dans l'enregistrement; status indique 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
    }
  ]
}


		
Réponse
Champ
Type
Description
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 moment précis en format ISO 8601, avec un fuseau horaire. 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.
Exemple de requête
			
{
  "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
  }
}


		
Exemple de réponse
			
{
  "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.