Consignor Purchase Billing Applet (Internal)
The period record of what you owe a consignor: for one supplier and one billing period, one line per consigned item with its opening quantity, net purchases, closing quantity and the resulting quantity to bill. It stores this in its own billing tables — no FINAL, no journal, no stock movement, no creditor balance — so the amount owed still has to be raised as a supplier invoice and paid through a payment voucher. Get the lines right on the Create screen: SAVE on the edit screen keeps the lines as they were loaded, and the Payment tab cannot record anything.
Overview
The Consignor Purchase Billing Applet (Internal) records, for one consignor (a supplier who keeps ownership of the stock in your shops) and one billing period, which consigned items became billable and for how much. Each record has a header (period, company, branch, location, purchaser, status), the consignor, and one line per item with an opening quantity, net purchases, closing quantity, the resulting Quantity To Bill and its value and tax. The applet stores this in its own billing tables; it is not a generic document, so it has no FINAL step, posts no journal, moves no stock and creates no creditor balance. The amount you actually owe the consignor still has to be recorded as a supplier invoice and paid through a payment voucher.
The window title is Consignor Purchase Billing Applet; the sidebar entry is Internal Consignor Purchase Billing. It is the purchase-side counterpart of the Consignment Billing Applet (Internal), which bills your customers for stock you consigned to them.
Where it fits
| Position | Applet / document | Relationship |
|---|---|---|
| Module | Purchasing, Inventory | Consignment-purchase family |
| Upstream (source of the figures) | Consignment GRN (Internal), Consignment GIN (Internal), Consignment Return (Internal), Stock Balance | The GRN and GIN are the documents that move consigned stock; the opening, net-purchase and closing quantities you type on a billing line come from them. The applet does not read them itself (see Lifecycle). |
| Upstream (commitment) | Consignment Purchase Order (Internal) | The order that placed the stock with you. Not linked to the billing. |
| Master data | Supplier, Employee, Organisation, Doc Item Maintenance, Tax Configuration | Consignor entity, purchaser, company/branch/location, consignment-flagged items, SST/WHT codes |
| Downstream | Purchase Invoice (Internal), Payment Voucher (Internal) | Nothing in the code links a billing to them; they are where the creditor balance and the payment are recorded. |
| Sales-side mirror | Consignment Billing Applet (Internal), Customer Consignment | You are the consignor there; here you are the consignee. |
Screens and menus
Sidebar: one entry, Internal Consignor Purchase Billing, which opens the listing. Settings and Personalization are the applet-level menus (below).
Consignor Purchase Billing Listing — server-side grid with columns Company Name, Branch, Consignor, Consignor Name, Start Date, End Date, Status, sorted by last update. Create (+) starts a new billing; clicking a row opens it for editing. The advanced-search box is the one inherited from the Purchase Order template (see Troubleshooting — it does not search billings). There is no FINAL, VOID, DELETE or PRINT button on the listing.
Create Consignor Purchase Billing — tabs Main Details, Account, Line Item, Payment; one button, CREATE. Edit Consignor Purchase Billing adds an Export tab and the buttons RESET and SAVE.
Select Line Item → Search Item — the item picker behind + on the Line Item tab. It lists only items whose consignment flag is set (columns Item Code, Item Name, Net Purchase, Closing Stock, Billed Quantity, Quantity To Bill — the last four are empty placeholders; the picker does not compute them). Choosing an item opens Add Item with two tabs, Item Details (price, quantity, discount, SST, WHT) and Calculations (opening, net purchase, closing, quantity to bill), and an ADD button.
Payment tab — a grid (Payment Voucher No, Payment Method, Date, Paid Amount, Remarks) with Total and Outstanding above it, + to open Add Payment (settlement-method picker and method-specific fields), and click-through to Edit Payment (SAVE / DELETE). Read Lifecycle before using it: nothing entered here is saved.
Export tab (edit only) — Printable Format drop-down and EXPORT AS PDF.
Settings menu (what an administrator sees, in order): System Configuration → Field Settings, Default Selection; Server Side Permissions → Permission Wizard, Permission Set, User Permission, Role Permission; Developer Tools → Release Notes. Opening Settings lands on Feature Visibility, which is not in the menu; Printable Format Settings and Webhook are likewise not in the menu and are reached by appending settings/printable-format-settings or settings/webhook to the applet’s address. Permission Wizard and Release Notes show the 404 page in this applet. Personalization lists Field Settings (404), Default Selection and Sidebar.
Configuration
Before you can use it
| Prerequisite | Where | Why |
|---|---|---|
| Company, branch and location | Organisation | Branch and location are the only header fields the form requires; the company is overwritten on save with the branch’s company. The server rejects a header whose company is missing or unknown (…_HDR_OBJECT_GUID_COMP_IS_NULL / …_COMP_DOES_NOT_EXIST) and a branch, location or consignor that does not exist. |
| The consignor as a supplier entity | Supplier | Picked on the Account tab. Neither the form nor the server insists on one — see Troubleshooting for why you should always pick one. |
| Employee records | Employee | The Purchaser Agent picker lists employees. |
| Items with the consignment flag set | Doc Item Maintenance | Search Item lists only items with the consignment flag on; an ordinary item never appears. The line’s default price is the item’s base-UOM price. |
| SST / WHT tax codes | Tax Configuration | The Item Details tab has SST and WHT pickers. |
Settlement-method items (items with a SETTLEMENT_TYPE) | Doc Item Maintenance | Populate the Payment tab’s Settlement Method list. Only needed if you want the tab to render; it cannot save. |
Server-side permissions API_TNT_DM_ERP_CONSIGNOR_PURCHASE_BILLING_* | Settings → Permission Set / User Permission / Role Permission | See Feature visibility / permissions. |
Not needed: default GL codes, document numbering, cashbooks, e-Invoice settings. The billing posts nothing and has no document number (the listing has no number column).
Applet settings
The applet has its own Default Selection and Field Settings screens and no inline settings gear. Only one setting actually does anything. Any user who can open Settings can change it.
| Setting | What it controls | Default | Effect when changed |
|---|---|---|---|
PRINTABLE (Printable Format Settings → set as default) | The printable format pre-selected in the Export tab’s drop-down. | none — the drop-down is empty until a default is chosen | Read into the Export tab. It has no effect on the PDF itself, because the export effect ignores the selected format (see Lifecycle). |
Screens that look like settings but change nothing:
- Default Selection (
DEFAULT_BRANCH,DEFAULT_LOCATION): two drop-downs and a SAVE button. The screen always opens blank and SAVE stores nothing; Main Details never reads these values. The same applies to Personalization → Default Selection. - Field Settings: eight slide-toggles (Unit Discount, SST/VAT/GST, WHT, Blanket Order; Segment, G/L Dimension, Profit Center, Project) that save nothing; the document form shows every field regardless.
Document behaviour settings
No exposed control. There is no FINAL / VOID, no numbering, no approval workflow, no e-Invoice flag and no posting to configure.
Settings in other applets that control this applet
| Setting | Where it is set | Effect here |
|---|---|---|
| Consignment Item tick on the item | Doc Item Maintenance | Search Item lists every ticked item and nothing else. The tick belongs to the item, not to a supplier, and the list is not narrowed to the consignor chosen on the Account tab, so a line for another consignor’s goods is accepted without a word. Before CREATE, whoever prepares the billing matches each line to this consignor’s goods received notes for the period (or to the consignor’s own statement); a line with no receipt from this consignor does not belong on this billing. |
| Base-UOM price on the item | Doc Item Maintenance, Pricebook | Default Unit Price on Item Details; the applet also loads the pricing-scheme links it finds. |
| Supplier GL code, ID number and currency | Supplier | Copied into the read-only Account card for display only. |
SETTLEMENT_TYPE on settlement-method items | Doc Item Maintenance | Decides which fields Add Payment shows (CASH, CASH_BACK, CREDIT_CARD, VOUCHER, BANK_TRANSFER, MEMBERSHIP_POINT_CURRENCY, CHEQUE). |
Feature visibility / permissions
Client-side: no client-side permission is registered for this applet and the applet checks none, so the Feature Visibility screen is empty and nothing in the UI — prices included — is hidden per role.
Server-side:
| Permission | What it gates |
|---|---|
API_TNT_DM_ERP_CONSIGNOR_PURCHASE_BILLING_CREATE | The CREATE button |
…_UPDATE | The SAVE button; target-scoped to the billing row |
…_DELETE | Deleting a billing — header and lines, permanently; no button does this |
…_READ | Listing and opening billings. A row the user may not read comes back with only its guid and status PERMISSION_DENIED. |
…_OWNER, …_ADMIN | Satisfy every check above; tenant owner / admin also bypass |
…_MEMBER | Defined but not checked |
Fields
Main Details
| Field | Meaning | Required | Notes / validation |
|---|---|---|---|
| Company | Owning company | No (form) | Overwritten on CREATE and SAVE with the selected branch’s company; the server requires a valid company. |
| Branch | Owning branch | Yes | Decides the company: CREATE and SAVE replace the Company with this branch’s company, whatever the Company box shows. It also narrows the Location list. The server checks only that the branch and the location exist, not that the location belongs to the branch. A billing holds one branch and one location, so a consignor whose stock sits in three shops gets three billings for the period. Nothing refuses a second billing for the same consignor, location and period — see the dates below. |
| Location | Store the consigned stock sits in | Yes | Filtered by branch; must exist. |
| Purchaser Agent | Employee responsible | No | Label carries an asterisk but there is no validator. Opens Main Select Purchaser Listing (employees). Read-only on edit — it cannot be changed after save. |
| Status | ACTIVE / INACTIVE | Yes | Plain status column; INACTIVE rows still list and still open. |
The form also takes Start Date, End Date, Reference and Remarks, and all four are saved. Neither date is required by the form or by the server, so a billing can be saved with no period at all, and nothing compares its dates with another billing’s. The duplicate check is yours: before CREATE, filter the listing on Consignor and Start Date, and if this consignor already has a billing for this location and period, open that one instead. Two billings for one period double what you appear to owe. The header Remarks is also the only place on a billing where a note survives (line remarks do not, see below).
Account
A read-only card (Entity ID, Entity Name, Status, Email, Phone, GL Code, ID Number, Entity Type, Identity Type, Description, Currency) filled from the supplier picked in Select Consignor Listing. The picker embeds supplier create/edit sub-screens (addresses, contacts, tax, branches, categories, item pricing, companies, logins, payment configuration). No field is validated, so CREATE / SAVE do not wait for a consignor.
Line Item — Item Details
What a line keeps. CREATE saves, for each line, the item, the four quantities on the Calculations tab and six amounts: STD Amount, Discount Amount, Amount Net, Tax Amount, WHT Amount and Txn Amount. Everything else on these two tabs — unit prices, UOM, Quantity Base, the SST and WHT codes and rates, an edited item name and the line Remarks — is used to work those amounts out and then dropped, because the billing line has nowhere to keep it. If a line needs an explanation (a damaged unit written off, a price the consignor agreed by phone), write it in the header Remarks on Main Details.
| Field | Meaning | Required | Notes / validation |
|---|---|---|---|
| Item Code / Item Name | From Search Item | — | Code read-only; the name can be edited but is not saved (above). As read from the code and not yet tried, the Line Item grid’s Item Code column looks for a value the billing line never carries, so it stays blank even on the Create screen. Add one line and look at the grid: if the code is blank, tell your lines apart by their quantities and amounts, and add items in an order you can check against your list. |
| Unit Price STD (Excl. / Incl. of tax), by UOM variants, Unit Price Net, Unit Price Transaction | Prices | No | Defaults from the item’s base-UOM price; ≥ 0. |
| Unit Discount, Unit Discount by UOM | Discount per base unit, and the same per selected UOM | No | ≥ 0. Only the resulting Discount Amount is saved. The discount comes off before tax (Amount Net = STD Amount − Discount Amount), so it lowers the Txn Amount. Neither box refuses a discount larger than the price; the Amount Net then drops below 0 and ADD stays greyed out with no message. |
| Quantity Base | Quantity priced | Yes | Whole number ≥ 1; starts at 1. This is a separate figure from Quantity To Bill — the two are not tied together, and Quantity Base itself is not saved (see Txn Amount). |
| Quantity by UOM, UOM to Base Ratio | UOM conversion | No | Ratio read-only |
| STD Amount, Discount Amount, Amount Net | Computed | Net required | STD = price × quantity; Net = STD − discount |
| SST/GST/VAT code, rate, Tax Amount | Tax | No | Code from the SST picker; rate and amount read-only, and the rate shows as a fraction (0.06 for 6%). There is no Net Amount incl. tax box. The line treats the item’s default price as tax-inclusive, so picking a code does not add tax on top: the Txn Amount stays where it was and is split into Amount Net and Tax Amount. That is read from the code, not tried; check it on one line before you rely on it: note the Txn Amount, pick the code, and see whether the Txn Amount moves. Only the Tax Amount is saved. |
| WHT code, rate, WHT Amount | Withholding tax | No | Code from the WHT picker. WHT comes off the Txn Amount (Txn = Net + tax − WHT), and for the same tax-inclusive reason picking a code keeps the Txn Amount and raises the Amount Net to make room for it. Only the WHT Amount is saved, and nothing is withheld: the billing posts no tax payable and nothing reminds anyone to pay it over. Whether a payment to this consignor is subject to withholding is for your tax adviser to decide. If it is, record the deduction on the purchase invoice and the payment voucher, and track the remittance outside this applet. |
| Txn Amount | Net + tax − WHT | Yes | ≥ 0. The only figure a line adds to the tab’s Total, to the header total and to the Payment tab’s Outstanding. It is priced on Quantity Base, not on Quantity To Bill, so a line whose Calculations say 12 to bill carries the value of 1 unit unless you set Quantity Base to 12 yourself. You can type a Txn Amount and the line works back to Amount Net, tax and discount, but a figure above the standard price makes Discount Amount negative, and ADD greys out with no message. If the consignor’s agreed price has risen, correct the item’s purchase price before you start. Before CREATE, check the Total against the consignor’s statement for the period: that comparison is the only check on the amount. |
Line Item — Calculations
| Field (label as shown) | Meaning | Required | Notes / validation |
|---|---|---|---|
| Openning Quantity | Consigned stock on hand at the start of the period | On the form (≥ 1) — but ADD checks only the Item Details form, so it is not enforced | Default 1; a cleared field is reset to 1 |
| Net Purchaser | Net consigned stock received during the period | No | Default 0.00; cleared → 1 |
| Closing Stock | Consigned stock on hand at the end | No | Default 0.00; cleared → 1 |
| Quantity To Bill | Opening + Net Purchase − Closing, recalculated on every change | No | Computed with integer parsing — decimals are dropped before the sum. Editable; the last computed value wins if you change an input again. |
Payment — Add Payment
The settlement type on the settlement-method item you pick decides which boxes appear. Every method asks for Amount and Remarks, and every method except VOUCHER asks for a Date. On top of that, CASH_BACK adds Cash Back and a read-only Cash Back for Settlement; CREDIT_CARD adds Card No, Name on Card, Card Issuer, Type, Card Expiry (year and month) and CVV; VOUCHER adds Voucher #; BANK_TRANSFER adds Transaction No; MEMBERSHIP_POINT_CURRENCY adds Point CCY and Point Currency for Settlement; CHEQUE adds Cheque No. ADD enables once Amount is at least 0.01 and every box except Remarks, Type and Cash Back for Settlement is filled.
Behind the boxes, the seven methods are the same. The code that would have handled each method differently is switched off for all seven. For five of the seven it was written to record money coming in, as a sales receipt does, so switching it back on would not record a payment to a consignor either. ADD copies only Amount onto a draft line and is then refused (next section). The method, date, reference numbers and card details are discarded and never stored, and Outstanding never goes down.
Record the payment where it can be recorded: raise the purchase invoice for the billing’s Total, pay it with a Payment Voucher, and look at that invoice’s open balance, not this tab, to see what is still owed for the period.
Export
Printable Format — formats whose transaction type is INTERNAL_CONSIGNOR_CONSIGNMENT, pre-selected from PRINTABLE; EXPORT AS PDF.
Lifecycle and effects
Statuses. ACTIVE and INACTIVE, chosen on the form; the server fills ACTIVE when the value is missing. There are no transitions, no FINAL and no VOID — a billing can be edited at any time in either status. Rows with status DELETED are excluded from every query, but nothing in the applet sets that status; the only removal path is a delete by support, which removes the header and its lines permanently.
Posting proof block
| Item | Value |
|---|---|
| Server document type | None. The applet writes its own billing records, not generic documents. (INTERNAL_CONSIGNOR_CONSIGNMENT, short code CSRCON, does exist as a generic type with amount and quantity signum 0, but the applet only uses that name as the printable-format transaction type and never creates such a document.) |
| Amount signum / quantity signum | Not applicable — no generic lines are sent. |
| Dr / Cr equation | None. Nothing posts a journal for a billing. |
| GL precedence | Not applicable. |
| Stock processor | None. No inventory transaction is written. |
| Open-queue rows (Knock Off Configuration) | None created; no downstream document can pick a billing up. |
| What VOID reverses | There is no VOID. |
What CREATE sends. The header from the form (company replaced by the branch’s company; the amounts and the open balance summed from the lines) plus the lines. Payment lines are not included. The server checks that the company, branch, location, consignor and items exist; it does not validate any amount or quantity. The success toast reads “The purchase order has been created successfully” (inherited text).
What SAVE sends. The header from the form, and the lines exactly as they were loaded from the server. Lines you add, change or delete on the edit screen therefore disappear after SAVE. Header changes (dates, branch, location, status, reference, remarks, consignor) are saved.
Payments. Add Payment → ADD runs a check against the outstanding balance that can never pass, so every attempt ends with the snack-bar “Payment Exceeds Outstanding” and nothing is added to the draft. Even a line that got past the guard would not be sent (see CREATE / SAVE above) and would not appear in the Payment grid when the billing is reopened. No payment voucher, cashbook entry or creditor knock-off is involved at any point.
Quantity To Bill. Computed in the browser as opening + net purchase − closing. The server can work these figures out itself (opening stock from inventory movements, net purchase from GRN and GIN lines) but the applet never asks it to; the three quantities are whatever you type.
Export. EXPORT AS PDF uses the Purchase Order print with a fixed template; the format chosen in the drop-down is ignored. Expect the error toast unless that template accepts a billing guid; the success toast, if any, reads “Purchase Order Exported Successfully”.
Related applets
- Consignment GRN (Internal) and Consignment GIN (Internal) — the documents that receive and issue consigned stock and therefore the source of the opening, net-purchase and closing quantities; neither is linked to the billing by the code.
- Consignment Purchase Order (Internal) — the commitment that placed the stock; its own Payment tab is equally non-functional and its page points here.
- Consignment Return (Internal) — returns to the consignor that should reduce the net-purchase figure you bill.
- Purchase Invoice (Internal) and Payment Voucher (Internal) — where the amount owed to the consignor becomes a creditor balance and is paid; the billing itself does neither.
- Consignment Billing Applet (Internal) and Customer Consignment — the sales-side mirror, where you are the consignor.
- Supplier, Employee, Organisation, Doc Item Maintenance, Pricebook, Tax Configuration — master data the form reads.
- Stock Balance — where to look up the opening and closing quantities before typing them.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| ADD on Add Payment always shows Payment Exceeds Outstanding, whatever the amount | The outstanding-balance check can never pass. | Payments cannot be recorded in this applet as shipped. Pay the consignor through a Payment Voucher against a purchase invoice. |
| Lines added, changed or deleted on the edit screen are gone after SAVE | SAVE sends the lines as loaded from the server, not as edited. | Get the lines right on the Create screen. To change a saved billing’s lines, create a new billing for the period. |
| CREATE / SAVE stays disabled | Branch or Location empty, Status not chosen, or no line on the Line Item tab. Consignor and Purchaser are not checked. | Fill Branch, Location and Status; add at least one line. |
| Success toast says “purchase order” | Inherited toast text. | The billing was created; confirm in the listing. |
Listing fails to load, or a row shows CLIENT_VALIDATION_GUID_DOES_NOT_EXIST in the Consignor columns | The listing looks up each row’s branch, company and consignor. A deleted consignor yields the error code in its columns; a billing saved with no consignor (allowed by the form and the backend) makes the lookup dereference a null guid and the grid load fails. | Always pick a consignor before CREATE. If a bad row exists, ask support to delete it (no button exists). |
| Advanced search never finds anything | The search box is the Purchase Order one: it searches generic documents, which never match a billing. | Use the column filters in the grid instead. |
| Item is not in Search Item | Its consignment flag is off. | Set the flag in Doc Item Maintenance. |
| Quantity To Bill ignores decimals, or a cleared quantity turns into 1 | Inputs are parsed as integers; an empty opening / net / closing field is reset to 1. | Enter whole units; do not leave a quantity blank — type 0 explicitly for net purchase or closing stock. |
| Default Selection does not remember the branch / location | The screen saves nothing and never loads a stored value. | Choose branch and location on each billing. |
| Export produces an error, or a purchase-order layout | The Export tab uses the Purchase Order print with a fixed template; the chosen format is ignored. | No working export in this applet; use the Purchase Report. |
| Settings opens on an empty Feature Visibility page; Permission Wizard, Release Notes or Personalization → Field Settings show 404 | No client-side permissions exist for this applet; those three menu entries do not work here. | Use Permission Set / User Permission / Role Permission for access control; ignore the empty screens. |
| Save refused because the company is missing or not found | The branch’s company could not be resolved. | Check the branch’s company in Organisation. |
…_HDR_OBJECT_GUID_BRANCH_DOES_NOT_EXIST / …_STORE_DOES_NOT_EXIST / …_ENTITY_HDR_DOES_NOT_EXIST / …_LINE_OBJECT_FI_ITEM_GUID_DOES_NOT_EXIST | A referenced master record was deleted between selection and save. | Re-select the record. |
| Applet opens on the 404 page | The applet’s root address points at a page that does not exist. | Click Internal Consignor Purchase Billing in the sidebar; the normal launch URL goes straight to the listing. |