Deductions and credits

This page shows you how to withhold an amount from what you pay a payee, such as repaying an advance, and how to track how much of it has been taken. It also explains what isn't available in the V3 API yet.

What a deduction is

A deduction is an amount you take out of a payee's payments to you. You create it once, and Wingspan applies it to that payee's payables, recording each application. It reduces what the payee receives; it doesn't change the payable's contractual amount.

Deductions created through this API are applied after the payment amount is set (applicationType: PostPayment). They reduce the payee's net proceeds, and they appear on each payable's deductionIds and in amountDetails.deductions.

Create a deduction

Call POST /v3/payments/deductions.

curl -X POST "https://api.wingspan.app/v3/payments/deductions" \
  -H "Authorization: Bearer $WINGSPAN_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "payeeId": "q7Lm2VxR9tKd4WnB8sHc1Z",
    "deductionType": "AdvanceRepayment",
    "name": "Equipment advance",
    "detail": "Tablet issued 2026-09-01",
    "amount": 300.00,
    "currency": "USD",
    "priority": 1
  }'

// (trimmed)
{
  "id": "Dd6Wq1Zk8Tx3Nv5Lm9Rb2H",
  "payeeId": "q7Lm2VxR9tKd4WnB8sHc1Z",
  "deductionType": "AdvanceRepayment",
  "name": "Equipment advance",
  "amount": 300.00,
  "currency": "USD",
  "status": "Pending",
  "isActive": true,
  "applicationType": "PostPayment",
  "application": []
}

Field	Required	What it does
`payeeId`	Yes	The Payee to deduct from.
`deductionType`	Yes	`Garnishment`, `ChildSupport`, `AdvanceRepayment`, `Benefits`, `TaxWithholding`, or `Custom`. A category for your records and reporting.
`name`	Yes	A label for the deduction.
`amount`	Yes	The amount to deduct.
`currency`	Yes	The deduction's currency.
`detail`	No	Extra text shown under the name, such as an order reference.
`priority`	No	Relative priority when several deductions apply to the same payee.
`payerId`	No	The payer relationship record, when you need to name it.
`metadata`	No	Your own key-value pairs.

Important: Wingspan applies the deduction mechanically; it doesn't decide whether a deduction is lawful or how much you may withhold. Garnishments, child support orders, benefits, and tax withholding have legal rules about amounts and timing. Confirm your obligations with a qualified professional. This isn't legal or tax advice.

Track how much has been applied

Each time Wingspan applies the deduction to a payable, it adds an entry to application[] with amountDeducted, payableId, and appliedAt. status summarizes progress:

`status`	Meaning
`Pending`	Not applied yet.
`PartiallyApplied`	Applied to at least one payable, but the goal isn't met.
`Complete`	Fully applied, or stopped short. `Complete` doesn't always mean the full amount was taken; compare `amount` with the sum of `application[].amountDeducted`.

isActive is true until status is Complete. For a goal-based deduction such as an advance repayment, originalAmount holds the goal the applications count toward.

Find deductions with GET /v3/payments/deductions, filtered by payeeId, status, isActive, applicationType, or up to 100 ids:

curl -g "https://api.wingspan.app/v3/payments/deductions?filter[payeeId][eq]=q7Lm2VxR9tKd4WnB8sHc1Z&filter[status][anyOf][]=Pending&filter[status][anyOf][]=PartiallyApplied" \
  -H "Authorization: Bearer $WINGSPAN_TOKEN"

Change or stop a deduction

PATCH /v3/payments/deductions/{deductionId} changes name, detail, amount, priority, isActive, or metadata. Set isActive: false to stop applying it. DELETE /v3/payments/deductions/{deductionId} removes it.

Deductions from a bulk import

In a PayableImport batch, a row with a negative amount and a status other than Paid creates a deduction against that payee instead of a payable. The batch summary counts deductions separately, and the item's result holds the deductionId.

Deductions in payroll runs

A Contractor payroll run's breakdown reports deductionsCount and deductionsAmount for the payables in the run. See Payroll runs.

What isn't available yet

Credits. Adding an amount to a payee's payments with a credit isn't available in the V3 API yet. To pay someone extra, add a line item (for example lineItemType: Bonus) to a payable. Contact support if you need credits.
Recurring deductions and recurring credits. Standing rules that create a deduction or credit on every matching payable aren't available in the V3 API yet. Contact support if you need them.
Webhooks. Deduction webhooks aren't subscribable yet. Read the deduction to track it.