Skip to main content

Preview Vendor Credit Cost Impact

GET 
/api/vendor-credits/:vendor_credit/cost-impact

Get a read-only preview of what authorizing this vendor credit will do to stock quantity, to the cost of the credited goods, and to the amount owed to the supplier — per line and per receipt (FIFO) layer. Once the credit is authorized the same call reports what actually happened instead of a projection.

Required scope: accounting:read

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

This endpoint makes no changes.

Each line carries a cost_impact behaviour: return_goods (the goods go back to the supplier; stock drops when the return shipment is recorded), write_off_goods (the goods stay but cannot be sold; stock drops on authorize), reduce_cost (you keep the goods and the supplier charged too much; quantity is unchanged and the unit cost of the credited goods goes down — units still in stock get cheaper, units already sold get a cost-of-goods true-up), financial_only (only what you owe changes; stock quantity and cost are untouched).

For reduce_cost lines the credit's total spreads across every unit the purchase order line received (capped at the ordered quantity) — the per-unit reduction is the line total divided by spread_units, which only equals the entered amount when the credited quantity equals the received quantity. on_hand_value_change is the share that lowers the value of stock still held; cogs_true_up is the share that posts as a cost-of-goods adjustment for units already sold. The two always sum to cost_basis_change_in_tenant_currency.

Response fields:

  • status — preview (not yet authorized), held (authorized, cost change awaiting review), applied (authorized and applied) or not_applicable (no line changes cost).
  • quantity_change — units leaving stock (return and write-off lines only).
  • cost_basis_change_in_tenant_currency / on_hand_value_change / cogs_true_up / on_hand_units / sold_units — the cost split described above.
  • accounts_payable_change_in_tenant_currency — what you will owe the supplier less, gross of tax.
  • recommended_resolution and effective_dates — the accounting treatment the cost-change policy will pick. restate dates each layer at its own receipt date; prospective recognises the change on the day you authorize. period_state is locked and clamped_to names the first open day when a receipt date falls behind the accounting lock date.
  • Projected layer rows are dated by the resolution the policy would pick: effective_at is the layer's receipt day (tenant time) under a restate and the day the credit is authorized under a prospective change, with clamped_for_lock evaluated for that date; a row whose date falls behind the accounting lock date reports the first open day in effective_at — the day the recalculation will actually post it — and clamped_for_lock: true; restate_effective_at / restate_clamped_for_lock always carry the restate view so a panel can show the other option. Rows backed by an applied revaluation keep the revaluation's own instant.
  • will_hold_for_review / hold_reason / policy_rule / policy_mode — whether the cost change will wait in the Cost Change Inbox, and which rule decided that.
  • cost_change_set_id / cost_change_set_status — the cost change created on authorize, when one exists.
  • alternative_if_financial_only — the same totals if every cost-reducing line were treated as financial only, for side-by-side comparison. Carries on_hand_units, sold_units and will_hold_for_review for symmetry with alternative_if_reduce_cost (always 0 / false: a financial-only credit never reaches the cost-change policy).
  • alternative_if_reduce_cost — draft credits only: the same totals if every eligible line (a product line linked to a purchase order line, with no expense or vendor-return link) were set to reduce cost, so a credit recorded as financial only can still be compared against the reduction it would produce. null when no line is eligible, and on authorized credits. Carries on_hand_units / sold_units — the units the reduction would spread across, still on hand and already sold — and will_hold_for_review, whether the cost-change policy would hold that reduction for review rather than apply it on authorize.
  • lines[] — one entry per credit line with available (whether the chosen behaviour is possible for the line), the before/after unit cost, a plain-English consequence_sentence, and layers[] (one row per receipt layer: dates, quantities on hand and sold, unit cost before and after, the total delta, the effective date, and clamped_for_lock). For an applied credit each layer row also carries inventory_revaluation_id.
  • warnings[] — {code, message} entries. Codes: held_for_review, locked_period, all_units_sold, orphaned_layers, no_purchase_order_line, possible_duplicate_price_reduction (the purchase order line or invoice price was also reduced on or after the credit date — by the edit's document date or by when it was made, so a March invoice re-priced in September still counts; raised on draft and authorized credits alike — a likely double count; carries purchase_order_line_id, cost_change_set_id, vendor_credit_line_ids — the cost-reducing lines a "Record as Financial only" action switches — and links[]), and truncated.
  • truncated — true when more than 500 layers are affected; totals still cover every layer, only the listed rows are capped.

Authentication: Requires Bearer token (PAT).

status is evidence-based: preview (not yet authorized), held (a Cost Change set is awaiting review), applied (a live revaluation sourced to this credit exists), pending (authorized, but the recalculation has not produced a revaluation yet — figures are projections), dismissed (the latest set was dismissed; nothing landed), not_applicable (no cost-impacting lines). An authorized credit whose layers already carry exactly its contribution (a receipt booked net of an applied credit, a re-authorization that changed nothing) also reports applied: nothing is queued.

A projection compares the derived target — the layer's pre-credit basis (its cost with the stored Vendor Credit component added back) less every authorized credit and this one — with what the layer costs now, so a layer that already carries part of the credit is never reduced twice.

All amounts are in the tenant currency (currency_code); the credit's own currency is document_currency_code. Each layer row carries chargeable_quantity — the units the credit actually attaches to, capped at the ordered quantity in arrival order, which is what the recalculation applies. When one credit names the same purchase-order line on several lines, each line reports its proportional share of the layer movement, so totals are never counted twice. touches_closed_period mirrors the Cost Change Inbox's closed-period check.

Several lines on one purchase-order line. The goods move once, by the credit's total for that line; each line then reports its proportional share (total_cost_delta, on_hand_units, sold_units) while per_unit_reduction remains that line's own contribution.

Chargeable-unit cap. A layer only partly covered by the ordered quantity (an over-delivery) absorbs only its chargeable share, so its unit_cost_after moves by less than the nominal per-unit figure — the same amount the recalculation books. Realized figures (inventory_revaluation_id set) come only from the credit's latest authorization cycle; a held, dismissed or still-pending authorization always shows projections.

Request​

Responses​

OK

Response Headers
    Content-Type