Vendor Credits

📄️List Vendor Credits

Returns a paginated list of vendor credits. Supports Spatie QueryBuilder filters, sorting, and search. Each row is transformed via vendor credit object.

📄️Bulk Delete Vendor Credits

Bulk delete vendor credits. Same body shape as Bulk Archive.

Show a single vendor credit with all eager-loaded relations: supplier, purchase order, purchase invoice, warehouse, store, currency, tax rate, vendor credit lines (with product, PO line, nominal code, tax rate), allocations (with purchase invoice and allocator), payments, tags, and the linked accounting transaction.

📄️Update Vendor Credit

Update an existing vendor credit. Accepts the same fields as Create.

📄️Delete Vendor Credit

Delete a vendor credit and cascade-delete its related lines, allocations, accounting transaction, and any inventory movements restored by the manager. Will fail for credits that are referenced by posted / synced accounting data if business rules prevent deletion.

📄️Get Vendor Credit Stats

Aggregate statistics for vendor credits: the number and remaining balance of open credits, the subset that is still fully unapplied, and the total amount ever allocated to purchase invoices.

📄️List Open Vendor Credits for Supplier

List open, non-archived vendor credits for a supplier that still have balance available to apply (payment status unapplied or partially applied), sorted by credit date descending. Useful for finding credits that can be allocated against the supplier's outstanding bills.

📄️List Applicable Vendor Credits for Invoice

List open vendor credits that can be applied to a specific purchase invoice (bill): credits from the same supplier, in the same currency as the invoice, that are not archived and still have a remaining balance. Sorted by credit date descending.

📄️Create Vendor Credit from Invoice

Create a vendor credit pre-populated from a purchase invoice (bill): the invoice's lines are copied onto the credit, the credit is opened immediately, and its full balance is applied against the source invoice. No request body is required.

📄️Update Vendor Credit Tags

Replace the full set of tags on a vendor credit. The tags array is required (send an empty array to remove all tags); each tag is a string of up to 64 characters. Tags that do not exist yet are created automatically.

📄️Archive Vendor Credit

Archive (soft-hide) a vendor credit. Returns a warning if it is already archived.

📄️Unarchive Vendor Credit

Unarchive a previously archived vendor credit. Returns a warning if it was not archived.

📄️Void Vendor Credit

Void a vendor credit. This reverses any inventory movements created by the credit (e.g. restock reversals) and reverses the linked accounting transaction. Idempotent: voiding an already-voided credit is a no-op.

📄️Close Vendor Credit

Close a vendor credit — marks it as fully settled so no further allocations or edits are allowed. Typically called after the credit has been fully allocated or refunded.

📄️Authorize Vendor Credit

Authorize a draft vendor credit, transitioning it to open. Authorization posts the credit's accounting transaction, records the FIFO cost layers consumed by the credited quantities, and creates planned inventory allocations for lines marked for restock.

📄️Unauthorize Vendor Credit

Revert an open vendor credit back to draft. This reverses everything authorization created: planned inventory allocations, write-off inventory movements, FIFO layer usages, and the accounting transaction.

📄️Reopen Vendor Credit

Reopen a closed vendor credit, making its remaining balance available to allocate or refund again. No request body is required.

📄️Preview Vendor Credit Write-Off Impact

Get a read-only preview of the order allocations that authorizing this vendor credit would consume when its write-off lines post their outbound decrement. Each row is one product whose stock the write-off would remove, split into free, soft-reserved and hard-allocated quantities, and lists the affected sales-order allocations highest-priority first so you can see which orders — and which printed shipping labels — would be demoted or voided before you authorize the credit.

📄️Allocate to Purchase Invoice

Allocate part or all of the vendor credit's remaining balance to a purchase invoice (bill).

📄️Batch Allocate to Purchase Invoice

Apply several vendor credits to a single purchase invoice (bill) in one atomic batch. Powers the 'Credit this bill' allocation flow, where a buyer distributes multiple outstanding credits from the same supplier against one bill at once. The whole batch is all-or-nothing: if any single allocation fails validation or over-allocates, none of them are saved.

📄️Unallocate (Delete Allocation)

Remove an allocation from a vendor credit. Returns 404-style error if the allocation does not belong to the specified vendor credit. Restores the vendor credit's remaining balance and the purchase invoice's outstanding amount.

📄️Auto-Apply Vendor Credit

Automatically apply the credit's remaining balance to the supplier's oldest open purchase invoices (bills), oldest first, until the balance is exhausted or no eligible bills remain. No request body is required.

📄️Record Vendor Credit Refund Payment

Record a refund payment against a vendor credit — money the supplier paid back instead of the credit being applied to bills.

📄️Update Vendor Credit Refund Payment

Update a refund payment previously recorded on a vendor credit. All fields are optional on update: payment_type_id, amount, payment_date, external_reference, currency_id. The updated amount cannot exceed the credit's remaining balance (the current payment's amount is excluded from that check), and currency_id must match the credit's currency.

📄️Delete Vendor Credit Refund Payment

Delete a refund payment from a vendor credit. The deleted amount becomes available on the credit again and the credit's payment status is recalculated.

📄️List Return Shipments

List all return shipments for a vendor credit, with lines, product, warehouse location, shipping method and creator eager-loaded.

📄️Create Return Shipment

Create a return (RTV) shipment against an authorized vendor credit. For each restock product line, posts the outbound inventory movement (negative adjustment) and transitions the matching planned allocation to fulfilled.

📄️Update Return Shipment

Update an existing return (RTV) shipment. Reverses the prior movements/allocations, then re-posts them from the new lines. For each restock product line, posts the outbound inventory movement (negative adjustment) and transitions the matching planned allocation to fulfilled.

📄️Delete Return Shipment

Delete a return shipment. Reverses the posted inventory movements (returning stock to its FIFO layers) and reverts the matching fulfilled allocations back to allocated.

📄️Update Return Shipment Status

Update only the status of a return shipment. Lightweight — no inventory/allocation side effects.

📄️Get Return Shipment

Get a single return shipment (goods sent back to the supplier under a vendor credit) with its lines, warehouse, shipping method, and creator. The response also includes a summary of the parent vendor credit (number, status, and supplier) under the vendor_credit key.

📄️Get Return Shipment Activity Log

Paginated audit trail for a return shipment and its lines, newest first. Each entry records the event, the changed attributes, and who made the change.

📄️Preview Vendor Credit Ship Impact

Get a read-only preview of the order allocations that creating a return shipment for this vendor credit's restock lines would consume. Each row is one product whose stock the shipment would remove, split into free, soft-reserved and hard-allocated quantities, and lists the affected sales-order allocations highest-priority first so you can see which orders — and which printed shipping labels — would be demoted or voided before you post the shipment.

📄️Bulk Archive Vendor Credits

Bulk archive vendor credits.

📄️Bulk Unarchive Vendor Credits

Bulk unarchive vendor credits. Same body shape as Bulk Archive.

📄️Bulk Void Vendor Credits

Void multiple vendor credits at once. Target credits either by an explicit ids array, or set apply_to_all to true with an optional filters object to void every credit matching the filter.

📄️List Vendor Credit Notes

Paginated list of notes on the vendor credit, ordered newest first. Each note includes its author (`user`) relation.

📄️Add Vendor Credit Note

Add a note to the vendor credit. `note` is required.

📄️Delete Vendor Credit Note

Delete a single note from a vendor credit. Idempotent: returns success even if the note does not exist.

📄️Toggle Vendor Credit Note Pin

Toggle the pinned state of a note on a vendor credit. Pinned notes sort to the top of the note list. No request body is required.

📄️Get Vendor Credit Activity Log

Paginated audit trail for a vendor credit, newest first. Covers changes to the credit itself, its lines, and its return shipments and shipment lines. Each entry records the event, the changed attributes, and who made the change.

📄️List Vendor Credit FIFO Layer Usages

Read-only audit trail of the FIFO cost layers consumed or referenced when the vendor credit was authorized. Each usage records the credited quantity, the unit cost taken from the layer, whether the layer's available quantity was actually decremented, and details of the layer, product, and credit line involved.

📄️List Vendor Credit Inventory Movements

Paginated inventory movements posted against a vendor credit: write-off movements on credit lines and outbound movements from return shipments. Each row includes the product, warehouse, quantity, and the FIFO layer and unit cost where known; unit_cost_provisional is true for rows whose cost is estimated from the product's current unit cost because no layer was consumed.

📄️Get Vendor Credit PDF

Render the vendor credit as a PDF using the configured Vendor Credit template. Returns a PDF file (Content-Type: application/pdf) displayed inline. Customize the template in Settings → PDF Templates → Vendor Credit.

📄️Generate Accounting Transaction

Generate (or regenerate) the local accounting transaction for the vendor credit. Builds the transaction lines from the vendor credit and saves the accounting transaction. Returns an accounting transaction object with eager-loaded lines and nominal codes.

📄️List Vendor Credit Attachments

List all attachments for the given vendor credit, newest first. Each attachment includes the uploader (when loaded), a ready-to-use download_url, and OCR scan state (ocr_status: null, processing, pending_review, confirmed, failed, rejected, or duplicate_detected).

📄️Upload Vendor Credit Attachment

Upload a new attachment to the vendor credit. multipart/form-data with a single `file` field.

📄️Delete Vendor Credit Attachment

Delete an attachment (removes the stored file and the record). Returns 404 if the attachment does not belong to the vendor credit, and 422 if the vendor credit is archived.

📄️Download Vendor Credit Attachment

Stream the attachment file as a download (Content-Disposition: attachment). The response is the binary file content with the original file name and MIME type — not JSON. Returns 404 if the attachment does not belong to the vendor credit or the file is missing from storage.

📄️View Attachment Inline

Stream the attachment file inline (Content-Disposition: inline) for in-browser preview of PDFs and images. The response is the binary file content — not JSON. Returns 404 if the attachment does not belong to the vendor credit or the file is missing from storage.

📄️Upload Credit Memo for OCR

Upload a credit memo PDF to begin OCR extraction. multipart/form-data.

📄️Get Vendor Credit Extraction

Get a vendor credit OCR extraction record with extracted header fields, matched lines, and related records (supplier, purchase order, duplicate vendor credit, referenced purchase invoice, candidate purchase orders).

📄️Delete Vendor Credit Extraction

Delete a vendor credit OCR extraction record and its associated stored file. Returns 204 No Content on success. Returns 422 if the extraction is confirmed (confirmed extractions cannot be deleted).

📄️Stream Vendor Credit Extraction PDF

Stream the original credit memo PDF through the backend (avoids CORS issues with direct storage URLs). The response is binary PDF content (Content-Type: application/pdf, Content-Disposition: inline) — not JSON. Returns 404 if the file is no longer available in storage.

📄️Re-scan Vendor Credit Extraction

Re-dispatch OCR processing for an existing extraction (e.g. after a failed scan or to pick up improved matching). Asynchronous — returns a new tracked_job_log_id. Returns 422 if the extraction is already confirmed or the original file is no longer available.

📄️Create Vendor Credit from Extraction

Create a draft vendor credit from a reviewed OCR extraction. The OCR'd PDF is automatically attached to the new credit and the extraction is marked confirmed.

📄️Attach Extraction to Existing Credit

Attach the OCR'd PDF to an existing vendor credit that was created manually (instead of creating a new credit from the extraction).

📄️Apply OCR Results to Vendor Credit

Apply reviewed OCR extraction results onto an existing vendor credit (header values and/or lines).

📄️Reclassify as Supplier Invoice

Reclassify a vendor credit extraction as a supplier invoice extraction — used when the scanned document turns out to be an invoice, not a credit memo. The vendor credit extraction is converted and a purchase invoice extraction is returned. No request body. Returns 422 if the extraction is already confirmed.

📄️Scan Attachment with OCR

Trigger OCR processing for an existing vendor credit attachment. Only PDF attachments can be scanned (422 for other MIME types). Asynchronous — returns a tracked_job_log_id for the tracked job log endpoints. Returns 404 if the attachment does not belong to the vendor credit, and 422 if Vendor Credit OCR is not enabled in Settings → Invoice OCR.

📄️Get Latest Attachment Extraction

Get the latest OCR extraction for a vendor credit attachment, including extracted header, matched lines, and related records. Returns data: null (200) when the attachment has never been scanned. Returns 404 if the attachment does not belong to the vendor credit.