Deposits and schedules

A payment schedule splits one invoice or estimate into parts. You can ask for a deposit before you start work, then spread the rest into instalments, for example three monthly payments. Each part has its own due date, so reminders, late fees and (from March 2027) automatic card charges work part by part. The client always sees what is due now and can pay it in one click.

How schedules work

A schedule is attached to one invoice or estimate and is made of parts:

Every part has a label, an amount, a due date (or "on acceptance") and its own status.

The parts always add up

Amounts are worked out in integer minor units by the same money engine that computes your totals, and the parts always add up exactly to the document total. When a split does not divide evenly, the last part absorbs the rounding.

For example, 1,000.00 USD in three equal instalments becomes 333.33 + 333.33 + 333.34. A schedule whose parts do not add up to the total is refused with schedule_total_mismatch.

Instalment statuses

Paying a scheduled invoice

• The pay page and the client portal show the whole schedule and ask for the next amount due.
• The client may pay more than the next amount if they want to get ahead.
• Every payment, by card or recorded by you, is allocated to the parts oldest first. A payment that covers the deposit and part of the first instalment marks the deposit paid and the first instalment partially paid.

Deposits on estimates

Add a deposit to an estimate to be paid when the client agrees. When the client accepts the estimate online, a deposit invoice is created automatically and linked to the estimate, ready to pay. From March 2027 the same happens when a client signs a contract that has a deposit.

Reminders, late fees and auto-charge per part

Because each part has its own due date:

• Reminder sequences run against each instalment's due date and amount.
• Late fees are worked out per instalment.
• From March 2027, each instalment can be auto-charged to a client's saved card on its due date.

Add a schedule in the app

Through the API and MCP

PUT replaces the whole schedule. Send the parts in order; for each part give either input_percent or amount_minor, and either a due_date or due_trigger: "on_acceptance".

curl -X PUT "https://api.freeinvoiceautomation.com/v1/documents/0193f2b4-5a6b-7c8d-9e0f-1a2b3c4d5e6f/payment-schedule" \
  -H "Authorization: Bearer $FIA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: schedule-inv-0042-v1" \
  -d '{
    "installments": [
      { "kind": "deposit", "label": "Deposit", "input_percent": "30", "due_trigger": "date", "due_date": "2027-02-01" },
      { "kind": "installment", "label": "Instalment 1", "input_percent": "35", "due_trigger": "date", "due_date": "2027-03-01" },
      { "kind": "installment", "label": "Instalment 2", "input_percent": "35", "due_trigger": "date", "due_date": "2027-04-01" }
    ]
  }'

{
  "data": {
    "document_id": "0193f2b4-5a6b-7c8d-9e0f-1a2b3c4d5e6f",
    "installments": [
      { "position": 1, "kind": "deposit", "label": "Deposit", "amount_minor": "36000", "due_date": "2027-02-01", "status": "pending", "paid_amount_minor": "0" },
      { "position": 2, "kind": "installment", "label": "Instalment 1", "amount_minor": "42000", "due_date": "2027-03-01", "status": "pending", "paid_amount_minor": "0" },
      { "position": 3, "kind": "installment", "label": "Instalment 2", "amount_minor": "42000", "due_date": "2027-04-01", "status": "pending", "paid_amount_minor": "0" }
    ]
  }
}

Field names follow the stored schedule parts; see the endpoint pages for the exact request shape. Your systems can follow parts with the installment.due and installment.paid webhook events. When a client pays on the pay page, the checkout request can name the instalment it pays (installment_id).

Rules and edge cases

• Exact totals. The parts must add up to the document total; the last part takes the rounding.
• Schedules on sent documents. A sent document changes only by revision, so changing the schedule of a sent invoice is recorded as a new revision (proposed).
• Paying more than the next amount is allowed by default; the extra goes to the next parts.
• Voiding the invoice voids its open parts.
• One schedule per document. Setting a new schedule replaces the old one.

What the client sees

• The schedule on the pay page and in the portal, with each part's label, amount, due date and status.
• The next amount due, preselected for payment.
• Reminders for each instalment as its due date comes.

Permissions

Errors

Related