Purchase GIN (Internal)

Creates and finalises purchase-side Goods Issue Notes — a record that goods left your premises toward a supplier, for a return, a warranty send-back or a sample out for evaluation — linked line by line to the order, receipt or invoice they came from. Read this first: FINAL does not reduce stock, does not touch moving-average cost and does not post a journal; it is a traceable paper trail. If the goods must actually leave stock and the supplier’s account be debited, raise a Purchase Return instead, or a Stock Adjustment for the physical movement alone.

Overview

The Purchase GIN (Internal) applet creates and finalises Goods Issue Notes on the purchase side: a record that goods (returns to a supplier, warranty send-backs, samples going out for evaluation) left your premises, addressed to a supplier entity. Warehouse or purchasing staff open it after a Purchase Order, GRN or Purchase Invoice exists and before the supplier’s credit note or replacement arrives.

Read this before anything else: in the backend the Purchase GIN is a zero-movement, zero-value document. Its server document type INTERNAL_PURCHASE_GOODS_ISSUED_NOTE (short code PURGIN) carries quantity signum 0 and amount signum 0, so FINAL does not reduce stock, does not touch Moving Average cost and does not post a journal. It is a traceable paper trail, linked line-by-line to the source document. If the goods must actually leave stock and the supplier’s account must be debited, use Purchase Return (Internal) (quantity signum −1, amount signum +1) instead, or a Stock Adjustment for the physical movement alone.

Where it fits

Module: Purchasing. The GIN sits between receiving and settlement, but it moves neither stock nor money.

Screens and menus

The applet has two menu items, Internal Purchase GIN (the document listing) and Line Items (every GIN line across documents, searchable by document number, item code, item name and quantity). HIDE_LINE_ITEMS_MENU removes the second item.

Listing. Columns: Purchase GIN No, Posting Status, Branch, Supplier Name, Purchaser, Updated Date, Created Date, Transaction Date, Created by. Toolbar: Create (+), search, advanced search, rows-per-page, a grid/pivot toggle, an inline settings gear, and a FINAL button that finalises every selected non-FINAL row. There is no VOID or DISCARD action anywhere in this applet’s code.

Create form tabs: Main Details, Account (Entity Details, Bill To, Ship To), Lines, Payment (hidden by HIDE_PAYMENT_TAB), Department Hdr (hidden by HIDE_DEPARTMENT_HDR_TAB). The CREATE button stays disabled until Main Details is valid, at least one line exists and the supplier form is valid.

Edit form (opened by clicking a listing row) shows the same tabs plus Contra, Doc Link, Attachments and Export, with RESET, FINAL (hidden by HIDE_FINAL_BUTTON), SAVE and, for non-FINAL documents, a two-click DELETE. The tab order is configurable (Default Selection, “Details Panel Ordering”) and the same panels can be rendered as vertical expansion panels (VERTICAL_ORIENTATION).

Line editor (Add / Edit Line Item): Item Details (Main Details, Delivery Instruction, Department, Doc Link, Delivery Details sub-tabs), Pricing Details, Issue Link, plus Serial Number / Batch Number / Bin Number tabs that appear according to the item’s sub-item type, and Costing Details.

Settings menu (System Configuration): Application Settings, Default Selection, Printable Format Settings; plus the shared Webhook, Feature Visibility and the five permission listings. Personalization: Default Selection (personal) and Sidebar.

Configuration

Before you can use it

• Company and branch with a main location, in Organisation. Branch, company and location are required on every GIN; picking a branch fills company and currency from the branch record.
• Supplier entities in Supplier. Entity ID is required; credit terms are offered from the supplier’s own CREDIT_TERMS extension rows and the field is disabled until a supplier that carries them is chosen. There is no doc_entity_hdr_json on a supplier record: that column lives on the document, and holds the copy of the supplier taken when the note was issued — see Purchase Credit Note — the supplier on this note is a copy.
• Items in Doc Item Maintenance / Inv Item Maintenance. Serial, batch and bin tabs follow the item’s sub_item_type.
• Running numbers for INTERNAL_PURCHASE_GOODS_ISSUED_NOTE are assigned by the backend on FINAL, so the document-numbering configuration for this server document type must exist before the first FINAL.
• Not required: default GL codes, tax codes, cashbooks and settlement methods. The GIN posts nothing (see Lifecycle), so none of the MISSING_DEFAULT_GL_CODE / MISSING_CASHBOOK prerequisites of the invoice family apply.
• Backend permissions: TNT_API_DOC_INTERNAL_PURCHASE_GOODS_ISSUED_NOTE_CREATE / READ / UPDATE / DELETE_TGT_GUID. FINAL uses the UPDATE permission.

Applet settings

Where settings live:

Master settings are saved by users of rank OWNER or ADMIN (through the Settings menu or the gear’s master mode). Personal mode on the gear is available to every user and stores only true overrides. A personal value wins over the applet-wide one.

The table lists every setting that is shown, saved and used by this applet. All are off / empty by default.

Read without a control (declared and consumed, but no shared or gear control exists for this applet code): HIDE_LINE_ITEMS_MENU (removes the Line Items menu; the shared toggle is rendered only for the delivery-order family), DEFAULT_ORIENTATION and DEFAULT_TOGGLE_COLUMN (column layout of the view-column container). They can be set only by another applet sharing the same settings store or by API.

Saved but never applied: DEFAULT_BRANCH and DEFAULT_LOCATION from Default Selection are persisted and the shared session effect loads the branch, but no component in this applet reads them, so a new GIN opens with an empty Branch. the default company is patched into a form that has no such control and is never saved.

Dead toggles: the inline gears offer 92 keys that nothing in this applet reads. 31 of them are not even declared in its model (for example HIDE_PO_LINE_WITH_GRN_KO_LISTING, SHOW_PO_FREE_GIFT_MENU, HIDE_EAN_CODE, HIDE_ETA, the MANDATORY_*_DATE external-document keys); the other 61 are declared and still unread, among them ENABLE_EDIT_PAYMENT_DATE, CANNOT_EDIT_CURRENCY_RATE, LOCK_PURCHASER_TO_CURRENT_USER, SHOW_BUDGET and the MANDATORY_* external-document and dimension keys. Flipping one on a gear saves a setting and changes nothing here. Likewise the 78 shared-screen toggles that this applet declares but never reads (HIDE_GENDOC_SAVE_BUTTON, the gen-doc void-button hide, HIDE_SERIAL_NUMBER, HIDE_BATCH_NUMBER, HIDE_BIN_NUMBER, HIDE_ENTITY_DETAILS_*, HIDE_CLIENT_DOC_*, SORT_ORDER, DEFAULT_POSTING_STATUS, and so on) are saved and ignored.

Document behaviour settings

• Posting behaviour is not configurable in the applet: FINAL is a fixed 0/0 document (see Lifecycle). FINAL_STATUS_GUID, VALIDATE_STOCK_ON_FINALIZE, the serial-validation-on-final switch (which the shared screen does not even show for this applet) and the workflow-status keys are not read by this applet.
• Printables: Printable Format Settings manages Jasper templates for the applet; Export calls POST …/internal-purchase-goods-issued-notes/print-jasper-pdf/{guid} with the selected template. ENABLE_PRINT_FINAL_GEN_DOC_ONLY and HIDE_EXPORT_AS_PDF_BUTTON are the only switches.
• Workflow / approval: none wired. HIDE_WORKFLOW_STATUS / HIDE_WORKFLOW_RESOLUTION are rendered on the shared screen but never read.
• e-Invoice: not applicable; the backend copies the entity’s skip_einvoice flag on FINAL but no LHDN submission exists for this type.

Feature visibility / permissions

Client-side permissions defined for this applet (22): SHOW_COSTING_DETAILS, SHOW_LAST_PURCHASE_PRICE and the twenty SHOW_* price / quantity / tax column codes matching the HIDE_UNIT_PRICE_*, HIDE_QTY_*, HIDE_AMOUNT_*, HIDE_UNIT_DISCOUNT*, HIDE_UOM_TO_BASE_RATIO, HIDE_TAX_CONFIG_SELECTION and HIDE_WHT_CONFIG_SELECTION settings. The line editor shows the field to a role that holds the code, even if the tenant setting hides it.

Checked in code but not seeded: INTERNAL_PURCHASE_GIN_DISPLAY_PRICING (the Lines tab and Line Items listing hide unit price and amount columns for users without it; OWNER / ADMIN rank passes ClientSidePermissionChecker regardless, so ordinary users see no prices until the code is seeded and granted) and SHOW_GENDOC_FINAL_BUTTON (pair of HIDE_GENDOC_FINAL_BUTTON). Seeded but never checked: SHOW_LAST_PURCHASE_PRICE.

Feature Visibility and Webhook are the shared screens; the applet adds nothing to them.

Fields

Main Details

Account

Lines

Payment and Contra

Lifecycle and effects

Statuses: a new GIN is saved as a draft (posting status empty). FINAL is the only transition the applet offers, from the listing (multi-select) or the edit form. A FINAL document is refused a second FINAL (HTTP 403 “already been posted to FINAL”). There is no VOID, DISCARD or “set to draft” action in this applet. DELETE (edit form, non-FINAL only) deletes the document.

What posting does:

What FINAL actually does:

1. Validation: forex rate; duplicate serial numbers within the document (always) — but a GIN’s serial numbers are stored, not checked against stock; bins; a refusal if the transaction date falls in a LOCK_ALL / LOCK_TXN period.
2. Update, assign running numbers, set the finalised date.
3. Start the main posting job, which sets off the follow-on jobs your tenant has switched on, after the company’s include / exclude list. The inventory job writes nothing and marks the stock as posted; the journal job, if switched on, fails with NO_JOURNAL_CREATED (the document stays FINAL); lines are opened for a follow-on document only if the company’s Knock Off Configuration has a row for the GIN.

Related applets

• Purchase Return (Internal) — the document to use when stock must leave and the supplier must be debited; the GIN is documentation only.
• Purchase GRN (Internal) and Purchase GRN Stock In (Internal) — the inbound counterparts; the GIN’s Purchase Order picker computes open quantity from IPO_IPGIN links, independently of GRN knock-offs.
• Purchase Order (Internal), Purchase Requisition (Internal), Purchase Quotation (Internal), Purchase Invoice (Internal) — purchase-side sources for GIN lines.
• Delivery Order (Internal), Sales Order (Internal), Jobsheet (Internal) — sales-side sources the picker also offers (e.g. returning a customer’s faulty unit to the supplier).
• Sales GIN (Internal) — the sales-side twin, same 0/0 shape.
• Consignment GIN (Internal) — unlike this applet, the consignment GIN moves stock and feeds MA cost.
• Stock Adjustment — the way to remove quantities physically sent out on a GIN when no Purchase Return is raised.
• Supplier, Organisation, Doc Item Maintenance, Inv Item Maintenance — master data the form depends on.

Troubleshooting

Related documentation

• Purchasing module
• Purchase Return (Internal) — for the document that actually moves stock and debits the supplier
• Standard procurement workflow — where GRN, invoice and return sit; the GIN is an optional dispatch record alongside it