Consignment Billing Applet (Internal)

The purchase invoice you owe a consignor once consignment stock has sold: it turns the consignment liability the Consignment GRN recorded into a real amount owed to a supplier, and the consignment stock into a purchase. It moves no stock and touches no customer, sale or output tax. The journal runs after FINAL, and the two consignment accounts come only from the company’s default GL codes — if either is unmapped the document stays FINAL with no journal, and Trace Document is where you find and resolve it.

Overview

The Consignment Billing Applet (Internal) raises the purchase invoice you owe the consignor once consignment stock has been sold. Consignment stock arrives on a Consignment GRN: it sits in your location but the consignor still owns it, recorded as consignment stock against a consignment liability. When it sells, ownership passes to you and the consignor bills you. This applet is where that bill is entered — it turns the consignment liability into a real amount owed to a supplier and turns the consignment stock into a purchase.

Server document type INTERNAL_PURCHASE_CONSIGNMENT_INVOICE, short code CSGINV. The counterparty is a supplier (the applet’s own entity picker is titled Select Supplier), the internal route is internal-purchase-invoice, and the file-import screen posts to the internal purchase invoice import endpoint. It is a purchase-side document in every respect.

Where it fits

Screens and menus

The left menu has three entries and no others:

Listing

One grid with 25 columns: Doc Short Code, Doc No, Doc No (Company), Doc No (Branch), Reference, Posting Status, Status, Branch Code, Currency, Supplier Name, Purchaser, Amount Txn, the five ARAP columns (PNS, Settlement, Doc Open, Contra, Balance), Created Date, Transaction Date, Client Doc Short Code and Client Doc 1–5. Above the grid: FINAL, DISCARD, VOID and SINGLE/MULTIPLE PRINT — the print button is disabled until a default printable format is set. Rows are multi-select; the buttons act on the selection.

Create

Seven tabs. Main Details, Account (Entity Details, Bill To and Ship To, with the picker titled Select Supplier) and Line Items are always there — see Fields. CREATE stays greyed out, with no message saying why, until Branch and Location are filled on Main Details, a supplier is chosen on Account and at least one line exists; if you cannot see what is missing, check those four. The other four tabs each disappear when a setting is on:

KO For → Consignment Purchase GRN is the intended way to build the document. The grid lists consignment GRN lines still waiting to be billed — read from the line open queue where server_doc_type_1 = INTERNAL_PURCHASE_CONSIGNMENT_GRN and server_doc_type_2 = INTERNAL_PURCHASE_CONSIGNMENT_INVOICE. Selecting rows and pressing KNOCK OFF copies the GRN header onto the draft and creates one billing line per GRN line, each with a document link back to the GRN. All rows picked in one document must share the same supplier and the same branch.

Edit

The edit panel adds six tabs to the create set and drops KO For (knock-off from that point on is per line): ARAP, Posting, TraceDocument, Contra, Doc Link and Attachment. Its buttons are RESET, FINAL, DISCARD, VOID and SAVE, each shown according to the document’s status and the settings in Document behaviour.

Line editing has its own tab set: Item Details, a sub-item tab (Serial Number, Batch Number or Bin Number, depending on the item), Costing Details when HIDE_COSTING_DETAILS is off, Issue Link, and a pair of KO By / KO For tabs for each of Purchase GRN, Purchase Order, Purchase Requisition and Supplier Delivery Order — each pair rendered only when the company has enabled that document flow into INTERNAL_PURCHASE_CONSIGNMENT_INVOICE.

File Import

Upload a .csv with a comma or pipe delimiter and press SUBMIT. Sample Format downloads a template. The screen is the internal purchase invoice importer, and the downloaded template is named Sales_Invoice_Master_Data_Template.csv regardless of the delimiter chosen.

Past batches and their per-row results are on the File Import listing.

Configuration

Before you can use it

Applet settings

Settings live on the shared settings screen (the field-settings route). Any tenant administrator with access to the applet’s Settings menu can change these; there is no per-row authority difference.

The settings menu has exactly three entries: Application Settings (the shared screen), Default Selection, and Printable Format Settings. A Knock Off Settings screen exists as a route and a component but its menu entry is commented out, so it is unreachable. The Personalization menu has one entry, Default Selection.

The applet’s settings model declares 103 keys. Of those, 52 pass all four proofs — declared, rendered on the shared screen for applet code internalConsignmentBillingApplet, persisted by the settings service, and read by this applet’s own code. Grouped by what they do:

Each HIDE_* key is paired in code with a SHOW_* client-side permission — the control is hidden only when the setting is on and the permission is absent. For this applet that per-role escape hatch does not exist: see Feature visibility and permissions.

Keys read at runtime with no control on the shared screen. Nineteen keys are read by the applet but have nowhere to be set from the Application Settings screen for this applet code:

• Seven tab-hide keys — HIDE_DELIVERY_DETAILS_TAB, HIDE_MAIN_PAYMENT_TAB, HIDE_MAIN_ARAP_TAB, HIDE_POSTING_TAB, HIDE_TRACE_DOCUMENT_TAB, HIDE_DOC_LINK_TAB, HIDE_DEPARTMENT_HDR_TAB — plus HIDE_KO_FOR_TAB. The shared screen does not offer tab toggles for this applet.
• HIDE_CURRENCY, HIDE_BASE_CURRENCY, ENABLE_MULTIPLE_KO, DEFAULT_COUNTRY, DEFAULT_CUST_TYPE, DEFAULT_CURRENCY. The last three pre-fill a supplier created inline from the document; no screen of this applet writes them (Default Selection writes branch, location and company only), so they are support-set or absent.
• PRINTABLE, DEFAULT_BRANCH, DEFAULT_LOCATION and DEFAULT_COMPANY, which are set on the other settings screens below rather than on Application Settings.

They keep whatever value the tenant already holds. On a tenant that has never saved Application Settings they are simply absent, so every gated tab renders.

Default Selection (applet-wide) has two controls, Default Branch and Default Location, and writes three keys: DEFAULT_BRANCH, DEFAULT_LOCATION and DEFAULT_COMPANY — the company is derived from the branch you pick, and picking a branch also pre-fills the location from that branch’s MAIN_LOCATION. The branch list is restricted to the branches your TNT_API_DOC_INTERNAL_PURCHASE_CONSIGNMENT_INVOICE_READ_TGT_GUID target allows, unless you are a tenant admin or owner, in which case it is unrestricted. RESET clears all three to null.

Personalization → Default Selection overrides the applet-wide values for one user and adds a third control, Default Item Search Item Type (DEFAULT_ITEM_SEARCH_ITEM_TYPE). It saves, but nothing reads it: the only lines that would apply it to the add-line item search are commented out, so the search returns the same items whatever you pick.

Printable Format Settings manages the printable formats offered to SINGLE/MULTIPLE PRINT and to the after-FINAL pop-up. Printing runs through the INTERNAL_PURCHASE_ORDER_PRINT_SERVICE Jasper service, so the format must be one that service can render.

Document behaviour settings

There is no approval flow on this document: the applet has no approval tab, no approval settings and no workflow designer, and the shared screen renders no approval controls for this applet code. See document approval for what “approval” means elsewhere in the product.

Settings in other applets that control this applet

Feature visibility and permissions

The applet checks 43 client-side permission codes — SHOW_GENDOC_FINAL_BUTTON, SHOW_GENDOC_VOID_BUTTON, SHOW_GENDOC_DISCARD_BUTTON, SHOW_DOCUMENT_DELETE_BUTTON, SHOW_TRANSACTION_DATE, SHOW_DOC_NO_TENANT / _COMPANY / _BRANCH, SHOW_INTERCOMPANY_PI_SCREEN and one SHOW_* counterpart for each hideable line and ARAP column.

None of them is defined for this applet, so no role, team or user can be granted any of them and every SHOW_* check comes out false. In practice that means each HIDE_* setting is absolute: switch it on and the control is gone for everyone, with no per-role exception.

Server-side permissions are unaffected. The applet requests TNT_API_DOC_INTERNAL_PURCHASE_CONSIGNMENT_INVOICE_READ_TGT_GUID, …_CREATE_TGT_GUID, …_UPDATE_TGT_GUID, TNT_TENANT_ADMIN and TNT_TENANT_OWNER at start-up; the create button and the SAVE button are disabled without create and update permission respectively, and the branch lists on Default Selection and the KO For grid are filtered by the read permission’s branch targets. A …_DELETE_TGT_GUID definition exists on the backend but the applet never asks for it.

Fields

Main Details

The form also carries External Remarks, and, when their settings allow, Delivery Branch and Delivery Location with an Apply to Lines button that copies them onto every line.

Check the Purchaser trap with one bill. Leave Purchaser empty, pick a Credit Terms value and type a Permit No, CREATE, then reopen the bill. If both boxes are empty, the trap holds on your tenant: choose a Purchaser, fill them again and SAVE.

Account

Three sub-tabs. Entity Details shows Entity Id (required), Entity Name, Status, Entity Type, Identity Type, ID Number, Currency, Email, Description and Phone Number, all populated from the selected supplier. Bill To and Ship To hold the two addresses.

Line items

A line starts from an item picked in the item search, which fills Item Code (read-only) and the unit of measure.

The line grid totals Total Txn Amount and Total SST/VAT/GST Amount above it.

Lifecycle and effects

FINAL is sent from the edit form or from the listing’s bulk FINAL as a posting-status update { posting_status: 'FINAL' }. Pressing FINAL on a document that is already FINAL shows This document has been posted. VOID first checks the document’s own links: if any ACTIVE link joins this document to an INTERNAL_PURCHASE_RETURN, the applet refuses with The invoice has already been linked with a purchase return; pressing VOID on a document that is not FINAL shows This document has not been finalized yet. Both are client-side guards.

What posting does:

Two consequences worth knowing. First, a Consignment GRN posts credit CONSIGNMENT_LIABILITY / debit CONSIGNMENT_STOCK; this document posts exactly the opposite pair, which is how the consignment holding is cleared as stock is bought. If a company is missing either default GL code, the GRN and the billing document both still go FINAL — the codes are read by the posting that runs afterwards, which fails — naming the code, or with NO_JOURNAL_CREATED on a GRN whose stock lines found no code — and leaves the document FINAL with no journal. Financial Report › Error Checking › Trace Document on that document reports Missing Journal; map the code first, then Resolve it there. Second, because the document total drives that pair, billing a part of a GRN clears only that part of the holding — the rest stays as consignment stock against consignment liability until it is billed or returned.

Related applets

• Consignment GRN (Internal) — the source of the lines this document bills; its open lines are what the KO For grid reads, and it cannot be voided once billed.
• Consignment GIN (Internal) — the outbound half of the consignment stock pair.
• Consignment Return (Internal) — the alternative to billing: send the stock back instead of buying it.
• Consignment Purchase Order — orders consignment stock from the consignor.
• Consignor Purchase Billing (Internal) — the period-level record of what is owed to a consignor; writes its own tables and posts nothing.
• Purchase Invoice (Internal) — the applet this one is cloned from; the file-import endpoint is shared with it.
• Purchase Return (Internal) — a link to one of these blocks VOID.
• Customer Consignment — the sales-side consignment record, for stock you own that sits at someone else’s location.
• Supplier — the consignor.
• Organisation — branches, locations, document numbering, knock-off configuration and the company posting configuration.
• Chart of Accounts — the CONSIGNMENT_LIABILITY, CONSIGNMENT_STOCK, PURCHASE, INPUT_TAX and creditor default GL codes.
• Tax Configuration — line tax codes.
• Doc Item Maintenance — the items the add-line search returns.

Troubleshooting

Related documentation

• Consignment purchasing guide — the end-to-end consignment process in user-guide voice.
• Purchasing module and Financial Accounting module.