Payment terms and early-payment discounts

Payment terms decide when an invoice is due. An early-payment discount lowers what the client owes if it pays by a deadline, such as 1% off within 10 days on net 30 (1/10 net 30). In Wingspan, you set terms once on the client and its engagements, and you offer the discount as a credit on the invoice.

Net terms

Set a term on each client's Payer record: due on receipt, net 15, net 30, or a custom number of days. You can also set a term on an engagement, for a client you bill on several engagements. Wingspan calculates each invoice's due date from the term, so you don't have to work out due dates yourself.

For an invoice sent on November 2:

Term	Due date
Due on receipt	November 2
Net 15	November 17
Net 30	December 2
Custom	November 2 plus the days you agreed on

To bill a client on a schedule, a recurring invoice takes the term on its template as paymentTermsDays, from 0 to 180, where 0 means due on receipt.

Everything after that keys off the due date:

When	What Wingspan does
Before the due date	The invoice is `Opened`. With `notificationPreferences.shouldSendReminders` set to `true`, Wingspan emails the client reminders.
On the due date	If automatic collection is on for the client, Wingspan collects what's due.
After the due date	An unpaid invoice moves to `Overdue`. Late fees in `lateFeeHandling` start from the due date.

Early-payment discounts

To offer 1/10 net 30, send the invoice on net 30, then create a credit on it for 1% of the qualifying lines. If the client pays, Wingspan applies the credit when the payment runs and collects the lower amount. A credit has no end date, so Wingspan doesn't expire it when the discount window closes. If the client misses the deadline, your system deletes or closes the credit before the client pays. 2/10 net 30 works the same way with 2%.

You don't edit the invoice at any point. It keeps its line items and amount, and the credit keeps its own ledger and PDF.

1. Send the invoice on net 30

A $1,200.00 shift and a $45.00 platform fee, sent on November 2. The invoice amount is $1,245.00, due December 2.

2. Create the discount credit

Discount only the lines that qualify. Here the shift qualifies and the fee doesn't, so the credit is 1% of $1,200.00. Target the invoice and record the deadline in metadata:

curl -X POST "https://api.wingspan.app/v3/payments/credits" \
  -H "Authorization: Bearer $WINGSPAN_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "payerId": "Pz4Rk8Wq2Tn6Lx9Vb3Mc1H",
    "invoiceId": "Iv7Hn2Qx5Rt8Kw3Lp6Zb9D",
    "amount": 12.00,
    "currency": "USD",
    "reason": "Promotional",
    "name": "Early-payment discount",
    "memo": "1/10 net 30: 1% off if paid by November 12",
    "metadata": { "discountDeadline": "2026-11-12", "terms": "1/10 net 30" }
  }'

// (trimmed)
{
  "id": "Cr4Hm8Wq2Tz6Lx9Vb3Nk1R",
  "invoiceId": "Iv7Hn2Qx5Rt8Kw3Lp6Zb9D",
  "applicationStrategy": "Manual",
  "name": "Early-payment discount",
  "amount": 12.00,
  "reason": "Promotional",
  "status": "Pending",
  "amountRemaining": 12.00,
  "entries": []
}

Until the client pays, the invoice shows the discount in pendingCreditAmount, and amountDueAfterCredits is the lower amount.

3. The client pays early, or doesn't

If the client pays on November 8, Wingspan applies the credit when the payment runs and collects $1,233.00:

// GET /v3/payments/invoices/Iv7Hn2Qx5Rt8Kw3Lp6Zb9D (trimmed)
{
  "status": "Paid",
  "amount": 1245.00,
  "creditIds": ["Cr4Hm8Wq2Tz6Lx9Vb3Nk1R"],
  "creditedAmount": 12.00,
  "pendingCreditAmount": 0.00
}

The credit becomes Complete with an Applied entry for the invoice.

If nothing is paid by the end of November 12, your system removes the discount. Delete the credit with DELETE /v3/payments/credits/{creditId}, which works while it has no entries. The client then owes $1,245.00, due December 2.

How the window works

Wingspan has no deadline field on a credit, so your system enforces the window.

Situation	What happens
Deadline	Your system decides it. Store it in the credit's `metadata`, and delete the credit if the invoice is still unpaid when the window closes.
Paying through Wingspan	The targeted credit applies when the payment runs, however the client pays.
Paying outside Wingspan	When you record an off-platform payment, Wingspan applies the credits that target the invoice and records the lower cash amount.
Payment fails or comes back	The credit stays applied. When the client pays again, Wingspan collects the reduced amount.
Automatic collection	Automatic collection runs on the due date. To give an automatic-collection client the discount, collect the payment inside the window.
The invoice changes before payment	Update the credit's `amount` with `PATCH /v3/payments/credits/{creditId}`. Its amount locks once it has an entry. A targeted credit must still fit the invoice.
You void the invoice	Delete the credit with `DELETE /v3/payments/credits/{creditId}`. That works while the credit has no entries.

Who does what

You create one credit for each invoice when you send it, with the amount that client's terms call for. Your system decides which lines qualify, the percentage, and when the window closes. Wingspan applies the credit when the client pays and records it on the credit's ledger. Credits need the payments.credit:read and payments.credit:write scopes.

GET /v3/payments/credits/{creditId}/pdf redirects to the credit PDF.