Skip to main content

List Expected Vendor Deposit Milestones

GET 
/api/purchase-orders/:purchase_order/expected-vendor-deposit-milestones

List the expected payment milestones for a purchase order, derived from its payment-term deposit schedule.

Required scope: purchase-orders:read

Grant this scope to your token under Settings → Developer → Personal Access Tokens.

Returns one row per schedule line. Per-shipment lines fan out into one row per inbound shipment (key line-{n}-shipment-{id}), plus a line-{n}-remainder row for PO value not yet assigned to a shipment. If the payment term has no schedule, a single synthesized Final Invoice Balance milestone (key synthesized-final-balance) covers the un-deposited remainder.

Each milestone's status is one of:

  • expected — planned but the trigger event has not happened yet
  • ready_to_create — the trigger has been reached; the milestone can be turned into a vendor deposit
  • created — a vendor deposit is already linked (linked_vendor_deposit_id)
  • out_of_sync — the linked deposit no longer matches the schedule (amount, due date, trigger, or shipment changed); see status_reasons
  • awaiting_invoice — (final-goods-invoice lines only) the trigger has been reached, so the amount is now owed under the term and settles when the supplier's bill is entered — no vendor deposit is ever created for it
  • invoiced — (final-goods-invoice lines only) a purchase invoice covers this milestone; see linked_purchase_invoice_id / linked_purchase_invoice_number

Use the key value with Create Vendor Deposit from Milestone to materialize a ready_to_create milestone. Only vendor_deposit settlement lines can be materialized — final_invoice_balance lines never become deposits and are rejected with 422.

line_index is the 1-based position of the line in the payment term's full schedule, counting every line regardless of settlement type.

Read-only. Requires the purchase-orders:read token scope.

Drift classification (schedule revisions): each milestone now returns drift_notes (string[]) alongside status_reasons. For deposits that are already settled (partially paid, paid, or applied), amount/due-date drift is informational only — the row stays created and the drift appears in drift_notes (money variance is owned by the shortfall/overage report). Only structural drift (trigger event or shipment linkage changed) or any drift on an unsettled deposit flags out_of_sync. When the deposit was created under an earlier schedule revision, the first note reads “This deposit was created under schedule revision N; the payment term is now at revision M.” linked_vendor_deposit_amount (number|null) is the linked deposit's recorded amount for old→new comparisons.

Provenance fields: linked_vendor_deposit_created_via (auto_schedule | milestone | manual), linked_vendor_deposit_created_via_label, and linked_vendor_deposit_amount_overridden_at (ISO timestamp when a user edited the amount after creation, null otherwise). These power the user-authored resync default and the provenance chips in the UI.

Bill Date milestones: a final_invoice_balance line whose trigger_event is invoice_date (trigger_event_label "Bill Date") dates each supplier bill from the bill's own date plus offset_days, with no shipment link or purchase-order event involved. Before any bill exists on the order, the row's basis_date is projected from the earliest date available — the earliest shipment's dispatch date (forecast_source shipment_dispatched), else the earliest shipment ETD (shipment_etd), else the purchase order's ETD (po_etd) — and due_date is that plus the offset. Once a bill exists, basis_date is the earliest real bill's date, due_date is that plus the offset, and forecast_source is actual_trigger_date.

Request​

Responses​

OK

Response Headers
    Content-Type