Skip to main content

Create Vendor Credit

POST 
/api/vendor-credits

Create a new vendor credit.

Not yet available to API tokens

This endpoint currently requires session authentication; Personal Access Token scope support is in progress.

Required fields:

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

Optional top-level fields:

  • purchase_order_id, purchase_invoice_id — Links to the source PO / bill.
  • 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) linked PO's currency if purchase_order_id is set, (2) the supplier's default pricing tier currency, (3) the tenant default currency. When a purchase_order_id is supplied, the currency MUST match the PO'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.
  2. A description-only line (service/rebate): description + quantity + amount (+ optional nominal_code_id).

Validation enforces that the requested quantity on any PO-line-linked line does not exceed (received_quantity - already_credited_quantity) for that PO line.

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 (use purchase_order_id for an actual link).
  • purchase_order_id (int) — Link the credit to an actual PO in SKU (return/damage credits). When linked, the credit's currency must match the PO's currency.

Request​

Responses​

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