Adjustments API
Preview and record credits, fees, discounts, tax corrections, refunds, and partial payments.
Adjustment endpoints change the balance or financial history of an invoice. Use the preview endpoint before you apply a fixed or percentage adjustment in a workflow for operators.
/v1/receivables/adjustmentsEndpoints and Schemas
| Method | Path | Request schema | Success response |
|---|---|---|---|
GET | /history/{invoiceId} | query: limit, offset | AdjustmentHistoryResponse |
POST | /preview | PreviewAdjustmentRequest | AdjustmentPreviewResponse |
POST | /credit | AddCreditRequest | AdjustmentResultResponse |
POST | /fee | AddFeeRequest | AdjustmentResultResponse |
POST | /discount | ApplyDiscountRequest | DiscountAppliedResponse |
POST | /tax | AdjustTaxRequest | TaxAdjustedResponse |
POST | /refund | IssueRefundRequest | RefundIssuedResponse |
POST | /partial-payment | RecordPartialPaymentRequest | PartialPaymentResponse |
DELETE | /discount/{invoiceId} | none | DiscountRemovedResponse |
DELETE | /fee/{invoiceId} | query: adjustmentId for a specific fee | FeeRemovedResponse |
All paths are relative to /v1/receivables/adjustments.
Common Request Fields
| Field | Type | Needed | Contract |
|---|---|---|---|
invoiceId | UUID string | yes for write bodies | Invoice must belong to the active organization. |
amount | decimal string | yes where present | Fixed adjustment amount, or percentage when isPercentage=true. |
isPercentage | boolean | no | Defaults to false; percentage discounts cannot exceed 100. |
description | string | no | Maximum 500 characters and retained in adjustment history. |
feeType | enum | no | late_fee, service_charge, processing_fee, or other. |
newTaxAmount | decimal string | tax only | Replaces the absolute tax amount; it is not an increment. |
paidAt | ISO 8601 date-time | no | Defaults to server time for partial payments. |
Preview Before You Apply
curl -X POST https://api.conduitt.io/v1/receivables/adjustments/preview \
-H "Authorization: Bearer ck_live_your_key" \
-H "Content-Type: application/json" \
-d '{
"invoiceId": "550e8400-e29b-41d4-a716-446655440000",
"adjustmentType": "discount",
"amount": "10",
"isPercentage": true
}'The preview response includes the current amount, calculated adjustment, new amount, and whether the operation is valid. Do not reuse a preview indefinitely. Refresh it when the invoice changes, before you submit the live adjustment.
Apply a Fee
{
"invoiceId": "550e8400-e29b-41d4-a716-446655440000",
"amount": "25.00",
"feeType": "late_fee",
"description": "Late fee under the agreed payment terms"
}Mutation responses return the affected invoice identifier, the adjustment result, and recalculated totals. Use those totals as authoritative and invalidate invoice detail, balance, aging, and adjustment-history caches after success.
Safety and Recovery
- never calculate the committed invoice total only on the client
- do not retry refunds or partial-payment mutations blindly after a timeout
- preserve the adjustment or payment identifier returned by the API for audit and recovery
- check adjustment history before you remove a fee or discount when many adjustments exist