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` and `Invoice.Overdue` fires. 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% that ends on the tenth day. If the client pays by then, Wingspan applies the credit when the payment runs and collects the lower amount. If it doesn't, Wingspan expires the credit and the client owes the full invoice. 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 number, 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. Start it on the day you send the invoice and end it on the deadline:

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",
    "startDate": "2026-11-02",
    "endDate": "2026-11-12",
    "externalId": "epd-INV-1102-0417",
    "lineItems": [
      {
        "documentLineItemId": "Li3Wx8Kq1Tz6Nv4Rb7Hm2P",
        "description": "1% early-payment discount on the shift",
        "amount": 12.00
      }
    ]
  }'

// (trimmed)
{
  "id": "Cr4Hm8Wq2Tz6Lx9Vb3Nk1R",
  "number": "CR-000124",
  "invoiceId": "Iv7Hn2Qx5Rt8Kw3Lp6Zb9D",
  "name": "Early-payment discount",
  "amount": 12.00,
  "reason": "Promotional",
  "startDate": "2026-11-02",
  "endDate": "2026-11-12",
  "status": "Pending",
  "amountRemaining": 12.00,
  "entries": []
}

Until the client pays, the invoice shows the discount in pendingCreditAmount.

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 completes with completionReason: FullyApplied, and Credit.Applied and Credit.Completed fire.

If nothing is paid by the end of November 12, Wingspan expires the credit on November 13. It writes an Expired entry, the credit completes with completionReason: Expired, and Credit.Completed fires. The client now owes $1,245.00, due December 2.

How the window works

Situation	What happens
Deadline	`startDate` and `endDate` are UTC dates, and both are inclusive. The credit can apply through the end of its `endDate`.
Paying through Wingspan	The credit applies when the payment runs, however the client pays.
Paying outside Wingspan	When you record an off-platform payment inside the window, the credit applies to it.
A check arrives after the window	The credit applies when you record the payment, whatever its `paidDate`. If a check the client mailed inside the window reaches you after the window closes, create a new discount credit with today's date as `startDate` and `endDate`, then record the check.
Payment fails or comes back	The credit stays applied. When the client pays again, Wingspan collects the reduced amount.
Paying in parts	The credit applies with the first payment that runs inside the window.
Automatic collection	Automatic collection runs on the due date, after the window, so the client pays the full amount. 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 and dates lock once it has an entry.
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 and end date that client's terms call for. Your system decides which lines qualify and the percentage. Wingspan applies the credit when the client pays inside the window, expires it after the deadline, and records each step on the credit's ledger and in webhooks. Credits need the payments.credit:read and payments.credit:write scopes.

A client linked to a Wingspan Account sees the same record as a deduction on its payable, with the same number. GET /v3/payments/credits/{creditId}/pdf redirects to the credit note PDF.