Recording credit notes and adjustments

This guide covers how to issue "negative" receivables (those that subtract debt) linked to a parent receivable: credit notes, returns, missing items, broken merchandise, adjustments and tax withholdings.

Negative types

Type	Use case
CREDIT_NOTE	AFIP credit note that partially or fully cancels an invoice
MISSING_PRODUCT	Missing product in a delivery
RETURN_PRODUCT	Product returned by the client
BROKEN_PRODUCT	Broken/damaged product
ADJUSTMENT	Adjustment in favor of the client (no specific fiscal cause)
RETENTION	Tax withholding applied by the client on the payment

Model

A child receivable is linked to its parent via parentReceivableId:

Effective balance of parent 99001: 45,000 - 5,000 - 1,350 = 38,650.

Create a credit note

POST /v1/receivables
Idempotency-Key: erp-nc-2026-05-20-001
Content-Type: application/json

{
  "receivableAccountId": 4242,
  "parentReceivableId": 99001,
  "amount": 5000.00,
  "currencyCode": "ARS",
  "receivableType": "CREDIT_NOTE",
  "legalNumber": "0001-NC-00001",
  "description": "Credit note for commercial discount"
}

Validations

Validation	Error if it fails
parentReceivableId required for negative types	missing-parent-receivable
Parent must belong to the same receivable account	parent-receivable-different-account
Parent must be in PENDING, PAID, or EXPIRED (not in a final state)	parent-receivable-not-modifiable
Parent must be a positive type (INVOICE or DEBT)	parent-receivable-invalid-type

Response

201 Created
Location: /v1/receivables/99100

{
  "id": 99100,
  "receivableAccountId": 4242,
  "parentReceivableId": 99001,
  "amount": 5000.00,
  "currencyCode": "ARS",
  "receivableType": "CREDIT_NOTE",
  "status": "PENDING",
  ...
}

List the children of a receivable

GET /v1/receivables?parentReceivableId=99001

Returns all child receivables of a given parent. Useful for displaying the breakdown of discounts applied to an invoice.

Tax withholding case

A withholding (RETENTION) represents the amount the client deducts from the payment due to tax application (IIBB, VAT, income tax, etc.). It is issued as a child receivable of the original invoice.

// The client notifies us they withheld 3% IIBB on $45,000
await maxpay.post('/v1/receivables', {
  headers: { 'Idempotency-Key': `erp-ret-iibb-${facturaId}` },
  body: {
    receivableAccountId: 4242,
    parentReceivableId: 99001,
    amount: 1350.00,            // 3% of 45,000
    currencyCode: 'ARS',
    receivableType: 'RETENTION',
    description: 'IIBB withholding 3%',
    invoiceData: {
      authCodeType: 'CERT_RETENCION',
      authCode: '2026-IIBB-1234567'
    }
  }
});

When the payment is collected, the client transfers 45,000 - 1,350 = 43,650. Both receivables (invoice and withholding) will be set to SETTLED when the settlement closes.

Operational restrictions

• Cancelling the parent before its children is not allowed. The children must be cancelled first, then the parent. See Lifecycle → cancellation.