Skip to main content

Create Vendor Credit

POST 
/api/vendor-credits

Create a new vendor credit.

Required scope: accounting:write

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

Required fields:

  • supplier_id (int) — Supplier the credit is from.

Optional top-level fields:

  • purchase_invoice_id — Link to the source bill. Purchase orders are derived from the lines (see Lines).
  • warehouse_id, store_id — For restock-type credits.
  • credit_type — One of: restock, unstock, service, overpayment, rebate.
  • refund_method — One of: applied_to_bill, cash_refund, retained_credit.
  • currency_id OR currency_code — Pick the credit's currency. If omitted, defaults are resolved in this order: (1) the currency of the first purchase order the lines reference, (2) the supplier's default pricing tier currency, (3) the tenant default currency. Every purchase order the lines reference must share the credit's currency.
  • tax_rate_id — Default tax rate for lines.
  • credit_date — ISO date (defaults to today).
  • supplier_reference — External RMA / credit reference from supplier.
  • vendor_credit_number — Auto-generated if omitted.
  • is_tax_included, is_for_overpayment — Booleans.
  • vendor_credit_note — Free-text note.
  • tax_lines, metadata — Optional arrays.

Lines (array, required for most credit types): Each line is either:

  1. A PO-line-linked line: purchase_order_line_id + quantity + optional unit_cost/amount/restock_inventory. Lines may come from different purchase orders, as long as every order belongs to the credit's supplier.
  2. A description-only line (service/rebate): description + quantity + amount (+ optional nominal_code_id).

Validation enforces, on every line whichever purchase order it comes from, that a stock-moving line's quantity (return_goods / write_off_goods) does not exceed (received_quantity - already_credited_quantity) for its PO line. reduce_cost and financial_only lines remove no units and are not bounded.

Reference fields:

  • vendor_credit_number (string, max 255, unique) — The supplier's credit memo number as printed on their document (e.g. "Credit Memo 0001669"). This becomes the credit's number in SKU. Leave blank/omit to auto-generate a local number (VC-00001, VC-00002, …). Supplying a number already used by another credit returns a 422 with a vendor_credit_number validation error.
  • supplier_reference (string, max 255) — Any additional reference on the supplier's document, e.g. their internal order number ("Credit Order 0010764"). The credit-memo OCR pipeline's duplicate detection matches an extracted memo number against BOTH supplier_reference and vendor_credit_number.
  • supplier_po_number (string, max 255) — The PO number printed on the supplier's memo, recorded as text for reference only. It does NOT link to a purchase order in SKU (link lines to purchase order lines via purchase_order_line_id for an actual link).
  • Purchase orders are not a header field: they are derived from the lines (purchase_order_line_id on product lines, financial_line_id on expense lines). A credit may reference lines from several purchase orders of the same supplier — a volume rebate or price allowance routinely settles goods bought on many orders. Every purchase order referenced must belong to the credit's supplier (otherwise 422 on that line's purchase_order_line_id / financial_line_id: "Purchase order PO-10231 belongs to a different supplier than this credit.") and share the credit's currency (otherwise 422 on currency_id, naming the order). The response reports the first order the lines reference as purchase_order.

credit_reason (optional) — why the supplier issued the credit. One of goods_returned, goods_damaged, price_correction, volume_rebate, short_shipped, overpayment, marketing_allowance, services_provided, other. Setting it defaults every line's cost_impact (product lines only; non-product lines are always financial_only) and derives is_for_overpayment. It is a default, not a lock — lines set explicitly keep their value.

lines.*.cost_impact (optional) — what the line does to stock and to the cost of stock: 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). Omit it and the line behaves as before (restock_inventory decides return vs write-off; non-product lines are financial only). reduce_cost requires purchase_order_line_id and cannot be changed once the credit is authorized. Responses report the effective value as cost_impact, whether an operator overrode the credit reason's default as cost_impact_explicit (a stored value equal to the reason's default is not an override and keeps following the reason), and which values the line may carry (with a reason for each unavailable one) as cost_impact_available.

A reduce_cost line's amount must not be negative (the credit's journal keeps the sign while the goods' cost can only be reduced to zero). Changing the credit reason re-defaults every line that was still following the previous reason's default; an overridden line keeps its behaviour. A default that would move stock beyond the received quantity is kept financial_only instead.

An explicit cost_impact of reduce_cost is refused (422 on lines.*.purchase_order_line_id) when the line has no purchase_order_line_id — a standalone credit has no receipts to adjust, so the behaviour cannot be stored even on a draft.

Request​

Responses​

Unauthenticated — the bearer token is missing, revoked, expired, or malformed. Never retry automatically; fix the credential. See the Errors guide.