---
title: Sample Delivery
order: 11
updated: 2026-07-21
---

# Sample Delivery

A *sample delivery* records a sample you hand to a customer for evaluation. While the sample is out it is subtracted from your sellable stock — so nobody can accidentally sell the same piece — and when the customer returns it, the quantity is added back. Returns can be **partial**: a customer may keep some pieces and send the rest back over time, in several separate return entries.

A sample delivery is **quantity-only**. It carries no price, discount, or tax on the goods themselves (samples are free of charge), so it never affects a sales order or any money figure — only stock. You may still attach *Additional Charges* (freight, packing, etc.) for the printed note's sake, but those are display-only and do not touch stock either.

## Open the Sample Delivery page

Open *Inventory → Stock*, then the actions menu (the ⋮ button in the top-right corner), and choose *Sample Delivery*. The Sample Delivery page opens.

Everything on this page is gated by the *View Sample Deliveries* permission (`delivery.seeSampleDeliveries`) — without it the page will not load. See [Permissions](#permissions).

## The list and how it is filtered

The page shows a paginated table (`20` rows per page) of your firm's sample deliveries, newest first. Each row shows the sample delivery number (a dash for entries created before numbering existed), the customer + contact person, the products (first two, then a `+N` overflow), the total quantity, who created it, the sample date, and a status chip. A row that has a return waiting for approval also shows a small amber *Return pending* chip.

Click any row to open its full detail view.

### What you can see

The list is **scope-filtered** on the server. Admins and users whose godown scope is `all` see every sample delivery in the firm. Any other user sees only the entries **they created** plus entries whose from-location falls inside their godown scope — so you can't browse samples dispatched from a warehouse you don't manage. This filtering is applied in the database, not just hidden in the UI.

### Search panel

Four cascading filters sit above the table:

- *Customer* — pick a customer.
- *Contact Person* — disabled until a customer is chosen; lists only that customer's contacts.
- *Product Head* — filter to deliveries that contain a product category.
- *Product Code* — disabled until a product head is chosen; lists only that head's codes.

Clearing a parent filter clears its child (clearing the customer clears the contact person; clearing the head clears the code).

### Status filter and your default view

A multi-select *All statuses* box sits next to the actions menu. Tick any combination of statuses to narrow the list; leave it empty to show everything. Your choice is **remembered on this device** — the page reopens on the same set next time. You can also set it from the actions menu under *Default Status* (with a *Reset* that clears back to "show all"). This is a personal preference stored in your browser, not a firm-wide setting.

## The statuses

Every sample delivery moves through this lifecycle:

- *Pending Delivery* (`pendingDelivery`) — created, but no delivery receipt has been uploaded yet. **Stock is not affected.**
- *Pending Approval* (`pendingApproval`) — a delivery receipt has been uploaded and it is waiting for a senior to approve. **Stock is still not affected.**
- *Delivered* (`delivered`) — a senior with the right permission has approved it. The quantity now **leaves sellable stock** at the godown/room/rack it was dispatched from.
- *Partially Returned* (`partiallyReturned`) — at least one return has been approved, but not every line is fully back yet.
- *Returned* (`returned`) — every line has been fully returned and approved. Stock is completely back.
- *Rejected* (`rejected`) — an authoriser declined the delivery before it was ever delivered. No stock effect. This is a terminal state.

The status is always recomputed by the backend from the underlying data — it is never set by trusting the client.

## Create a sample delivery

Click *Add Sample* (top-right of the search panel; only shown if you hold *Create Sample Delivery*). This opens the full *Add Sample Delivery* page — it is a routed page rather than a modal because the description fields use a rich-text editor.

The new entry is born as *Pending Delivery*. Creating it does **not** move any stock.

### Customer and contact person

Pick the *Customer Name*, then the *Contact Person Name* (the contact list is scoped to the chosen customer). The server verifies the contact person actually belongs to that customer — a mismatched pair is rejected with an error before anything is saved. Both are **required**, and both become **immutable** after create (editing later ignores any change to them).

### Sample Delivery Date

A date picker, defaulting to today. The date you can actually save depends on your permission:

- Without *Back-date Sample Delivery*, the date you pick is **ignored on create** and forced to today by the server. (The field still lets you pick one, but it won't stick.)
- With *Back-date Sample Delivery* (or as an admin), you may pick any **past** date. A future date is capped to today server-side.

### Product rows

Add one or more product rows. Each row has:

- *Product Category* (product head) — **required**.
- *Product Code* — **required**; disabled until a category is chosen, and scoped to that category. The server re-checks that the code really belongs to the chosen head. Picking a code also fetches the code's default description and its allowed units.
- *Quantity* — **required**, must be greater than `0`. Both the form and the server reject a zero or negative quantity.
- *Make* — optional; scoped to the head's allowed makes. If the category restricts makes, the server rejects any make outside that allowed set.
- *Unit* — the code's allowed unit(s). If a code allows exactly one unit it is auto-selected and locked. A unit is required to save.
- *Godown → Room → Rack* — the **from-location** the sample ships out of, all three **required**. These cascade: choosing a godown loads its rooms, choosing a room loads its racks, and if a level has exactly one option it is auto-selected. The dropdowns show the current per-location stock for the chosen code, and picking a code auto-fills the location holding the most stock (within your scope). The server verifies the full rack → room → godown chain, and that you hold **manage scope** on the location — a forged rack that doesn't belong to the claimed room/godown, or a location outside your scope, is rejected.
- *Description* — a read-only panel on the left shows the product code's default notes; a rich-text editor on the right lets you add your own note. On save the two are merged (default first, then your note). The description is capped at `20000` characters and is sanitised server-side.

Use *Add Product* to add more rows and *Remove* to delete one.

### Sample delivery number

Every sample delivery carries its own number. How it is set depends on your firm's numbering mode (see [Sample delivery numbering](#sample-delivery-numbering)):

- **Automatic** — the number is assigned server-side from the firm's running counter and format when you save. No number field appears on the form, and any number sent by the client is ignored.
- **Manual** — a required *Sample Delivery Number* field appears at the top of the form. Type any number up to `100` characters.

Sample delivery numbers must be **unique**: saving a new entry — or editing an existing one — with a number another sample delivery already uses is rejected with *"This sample delivery number is already in use"*.

A non-admin creating an entry in a manual-numbering firm still sees the field; if the app cannot read the firm's mode it falls back to automatic (field hidden).

### Additional Charges

Optionally add charge rows (freight, packing, handling, etc.). For each row:

- *Charge type* — pick from your firm's Additional Charge master. Required for every row you add.
- *Amount* — a number. It may be negative only if the selected charge type is configured to allow negatives; otherwise a negative amount is rejected (both in the form and on the server).
- *Tax %* — read-only. It comes from the selected charge type and cannot be edited here.
- *Remark* — optional free text, up to `300` characters.

A live *Total (incl. tax)* is shown. Only the charge id, amount, and remark are trusted from your browser — the title, tax rate, and negative-allowed flag are re-read from the charge master and snapshotted server-side, so a tampered title or tax can never be injected. These charges are for the printed note only; they never affect stock.

### Save

Click *Save Sample Delivery*. The form checks that customer, contact person, date, and every product's category/code/quantity/unit/godown/room/rack are filled, and that every charge row has a type chosen, before submitting. The saved entry appears in the list as *Pending Delivery*.

## Edit a sample delivery

From an entry's detail view, choose *Edit* (reuses the Add page). Editing is only possible **before the sample is delivered** — that is, while it is *Pending Delivery* or *Pending Approval* — and only by the person who **created** it (admins can edit any). Someone else, or an already-delivered entry, cannot be edited.

You can change the products, additional charges, sample date, attachments, and — in manual numbering mode only — the sample delivery number (still subject to the uniqueness check). Customer and contact person are locked. The sample date is only rewritten if you actually changed it **and** you hold back-date permission — otherwise the original stored date is kept untouched (a plain re-save never silently bumps a historical date to today). Removing every receipt file drops the entry back to *Pending Delivery*; adding one moves it to *Pending Approval*.

## Upload the delivery receipt

The delivery receipt is proof that the sample physically went out. It is what moves the entry from *Pending Delivery* to *Pending Approval*, ready for a senior to approve.

1. Open the sample delivery and, from its actions menu, choose *Upload Delivery*.
2. Drag in the receipt file(s) — up to `50 MB` per file — and optionally add a *Note* (transport details, remarks; up to `2000` characters). Save.
3. The entry moves to *Pending Approval* and records **who delivered** (the uploader, who need not be the creator).
4. While it is still pending you can add more files or flag existing ones for removal. **Removing every file drops the entry back to *Pending Delivery*** and clears the "delivered by" stamp.

Receipt files can only be changed *before* approval. Uploading requires *Create Sample Delivery* permission — the uploader is treated as the person who delivered, so it isn't limited to the original creator.

## Approve or reject

Both actions are done by a senior holding *Approve Sample Delivery*.

### Approve

Choose *Approve Sample Delivery* from the actions menu (only offered when the entry is *Pending Approval* — i.e. a receipt has been uploaded). On approval:

- The status becomes *Delivered*.
- The quantity **leaves sellable stock** at each product's from-location, effective on the **sample delivery date**.
- The approver must hold **manage scope** on at least one of the entry's from-locations (admins bypass this).

The stock movement shows in the product's stock ledger as a *Sample Out* entry. See [Stock history](/docs/inventory/stock-history).

### Reject

Choose *Reject*. This is only available while the entry is *Pending Delivery* or *Pending Approval* (i.e. not yet delivered), and it marks the entry *Rejected* with no stock effect. Rejection is terminal — a rejected entry cannot be re-approved.

## Returns

When the customer sends samples back, you record a *return entry* against the delivered sample. Returns are per-line and can be partial, and the same sample can accumulate several return entries over time.

### Create a return

1. Open a *Delivered* or *Partially Returned* sample and choose *Return Entry* (requires *Create Sample Return*).
2. The modal lists only the lines that still have something outstanding. For each, enter a *Return Qty* — you cannot return more than the **outstanding** amount, where outstanding = delivered − already-approved-returned − quantities on other still-pending returns. The server enforces this cap even if the form is bypassed.
3. Set the *Return Date* (defaults to today; back-dating is gated by the same *Back-date Sample Delivery* permission, and a future date is capped to today). Add an optional *Note* (up to `2000` characters) and optional proof file(s) (up to `50 MB` each). Save.

The return is created in *Pending Approval*. **The sample's own status does not change, and no stock moves, until the return is approved.**

### Approve or reject a return

A senior with *Approve Sample Return* sees *Approve* / *Reject* buttons on each pending return in the detail view.

- *Approve* — commits the returned quantity **back into stock** at each line's original location, and bumps each line's returned quantity. The approver needs **manage scope** on at least one of the return's locations. The sample then becomes *Returned* if every line is now fully back, or *Partially Returned* otherwise. If another return was approved in the meantime and this one would push a line past its delivered quantity, the approval is blocked with a conflict error. The movement appears in the ledger as a *Sample Return* entry.
- *Reject* — marks the return entry rejected with no stock effect. The outstanding quantity it was holding is freed for a fresh return.

## Print the sample delivery note

From the actions menu of any sample delivery (in **any** status) choose *Print Sample Delivery Note*. A PDF opens in the viewer — **nothing is emailed**; simply view, print, or close it. The note is quantity-only by design (no money columns).

The note's subject, opening paragraph, closing text, and terms come from your firm's *Sample Delivery Note* template. To change them, an admin (or a user with *Manage Quotation Personalisation*) edits the template under *Settings → Firm Customisation → Communication & Templates → Sales Communication → Sample Delivery Note*. See [Document templates](/docs/settings/document-templates#sample-delivery-note) for every field, default, and available token.

The sample delivery's own number is printed in the note's header block as a *Sample Delivery No :* row. An entry created before numbering existed simply has no such row.

The tokens `{customerName}`, `{contactPerson}`, `{date}`, `{companyName}`, `{sampleDeliveryNo}`, and `{products}` all work in the subject line, the opening paragraph, **and** the closing text, and each of those three fields on the template screen has a row of quick-insert token buttons under it — click one and the token lands at your cursor. `{sampleDeliveryNo}` prints the entry's number (nothing if it has none), so you only need it if you want the number inside your own wording. `{products}` prints a comma-separated list of the samples' products using each product head's **external display name** (falling back to the internal head name when none is set), de-duplicated ignoring case **and** spaces — so `Ball Valve`, `ball valve`, and `BallValve` print once.

## What the detail view shows

Clicking a row opens a full-screen view with:

- The *sample delivery number* in the header (omitted when the entry has none).
- *Customer* and *Contact Person* cards (name, GST, address, email, phone).
- An **audit rail**: *Applied by* (creator + time), *Delivered by* (who uploaded the receipt + time), *Approved by* (+ time), and the *Sample date*. Any delivery note you saved with the receipt is shown here too.
- The *Products* table (head, code, make, quantity + unit, returned quantity, and the godown › room › rack location). Expand a row to read its description.
- *Additional Charges*, if any (title, tax %, amount, remark).
- The *Returns* history — each entry's date, status, items, requested-by and approved-by, with the pending ones carrying inline *Approve* / *Reject* buttons. Expand an entry to see its lines, note, and any attached proof files.
- *Delivery Receipt Files* — click any file to preview or download it.

## Sample delivery numbering

Your firm chooses how sample deliveries are numbered in *Settings → Firm Customisation → Communication & Templates → Sales Communication → Sample Delivery Note → Sample Delivery Number → Configure*. See [Sample delivery number format](/docs/settings/document-templates#sample-delivery-number-format).

The *Sample Delivery Number* card is **firm-administrator only** — a non-admin who can open the *Sample Delivery Note* screen still sees the PDF wording fields, but not the numbering card. The modal has two tabs, *Format* and *Reset Numbering*.

### Format

- *Numbering mode* — *Automatic* (default) or *Manual*.
- **Automatic** uses a firm-wide running counter rendered through a format you set:
  - *Prefix* — a date-based lead, using the same date options as the quotation number (default `YYYY`, e.g. `2026`). See [Quotation number format](/docs/settings/document-templates#quotation-number-format) for the full list.
  - *Number padding* — how many digits the counter is zero-padded to. Range `1`–`10`, default `5` (so counter `1` prints as `00001`).
  - *Joiner* — the separator between parts: `Dash "-"`, `Slash "/"`, `Space " "`, or `None`. Default `-`.
  - *Suffix (optional)* — your own free text, added at the very end of the number with **no dash and no joiner**: prefix `2026`, padding `5`, joiner `-`, suffix `GST` prints `2026-00042GST`. Leave it empty for no suffix (the default). Spaces are ignored entirely — a space-only value counts as empty and `A B` becomes `AB`. Maximum `12` characters.
  - Sample deliveries have **no revision suffix**, so a typical auto number reads `2026-00042`. A live *Preview (next sample delivery)* shows how the next number will read.
- **Manual** hides the format fields; staff type the number (up to `100` characters) on each create.

### Reset Numbering

The second tab shows the *Current counter value* and lets an administrator set it to any value from `0` to `999,999,999`, behind a confirmation. The next automatic number is that value `+ 1`. Sample deliveries that **already carry a number keep it** — only newly created ones start from the new value. Resetting does nothing while the firm is in *Manual* mode.

Because numbers must be unique, reset the counter to a value your firm has not already used. A failed save can "burn" a number (leaving a gap), which is expected and harmless.

## Delete a sample delivery

Choose *Delete* to permanently remove an entry (a tombstone snapshot is recorded first for audit). Who may delete depends on the status:

- **Delivered / Partially Returned / Returned** — requires *Delete Sample Delivery*. Deleting one of these **re-adds** any still-out stock (the outbound movement disappears with the record).
- **Pending / Rejected** — the **creator** may delete their own, or anyone with *Delete Sample Delivery*.

Deletion cannot be undone.

## Permissions

Sample-delivery permissions live in the *Delivery* tab of a user's permissions (see [Users and permissions](/docs/settings/users-and-permissions)):

- *View Sample Deliveries* (`seeSampleDeliveries`) — open the page and view/print. Root permission; everything else depends on it.
- *Create Sample Delivery* (`createSampleDelivery`) — record a new one, edit a not-yet-delivered one, and upload/remove its receipt.
- *Approve Sample Delivery* (`approveSampleDelivery`) — approve a pending delivery (subtracts stock) or reject a not-yet-delivered one. Approval also needs **manage scope** on a from-location.
- *Create Sample Return* (`createSampleReturn`) — raise a return entry against a delivered sample.
- *Approve Sample Return* (`approveSampleReturn`) — approve or reject a pending return. Approval also needs **manage scope** on a location.
- *Delete Sample Delivery* (`deleteSampleDelivery`) — delete a sample delivery (depends on *Approve Sample Delivery*).
- *Back-date Sample Delivery* (`allowBackDateSampleDelivery`) — pick a past sample or return date (depends on *Create Sample Delivery*).

Beyond these, creating and approving also require the relevant **inventory manage-scope** on the godown/room/rack involved. See [Storage locations](/docs/inventory/storage-locations).

## Common questions

### When exactly does stock leave the shelf?

Only when a senior **approves** the delivery (moving it to *Delivered*). Creating the entry and uploading the receipt do **not** touch stock — they just move it through *Pending Delivery* → *Pending Approval*. The outbound movement is dated the sample delivery date.

### Can I approve a sample without uploading a receipt first?

No. Approval is only offered when the entry is *Pending Approval*, which requires at least one receipt file. Upload the delivery receipt first, then approve.

### Why can't I edit or delete someone else's sample delivery?

Editing is creator-only (before delivery), and pending/rejected deletes are creator-only too — unless you're an admin or hold *Delete Sample Delivery*. This keeps one person from quietly rewriting another's dispatch record. Already-delivered entries can't be edited at all.

### The customer returned only part of the sample — how do I record that?

Raise a *Return Entry* and enter the quantity actually returned on each line; leave the rest. Once approved, the sample shows as *Partially Returned* and the outstanding quantity stays out of stock. File another return later for the rest — you can never return more than is still outstanding.

### I picked a past sample date but it saved as today — why?

Back-dating the sample or return date needs the *Back-date Sample Delivery* permission. Without it the server forces the date to today, even though the picker let you choose another. Ask an admin to grant the permission if you need to record real-world dates after the fact.

### Does a sample delivery affect a sales order or any revenue?

No. Samples are quantity-only and free of charge — they only move inventory. Any additional charges you add are shown on the printed note but don't affect stock, orders, or money figures. To hand goods against an actual order, use a delivery instead; to hand goods before an order exists, see the [Delivery Note](/docs/inventory/delivery-challan).

### My older sample deliveries show a dash instead of a number.

Sample deliveries only started carrying a number recently, and nothing was renumbered retrospectively. Entries created before the change simply have none — they show a dash in the list, no number on the view screen, and no *Sample Delivery No :* row on the printed note. Everything created since is numbered.

### The Sample Delivery Number field isn't showing on the create form — why?

Your firm is in *Automatic* numbering mode, so the number is assigned by the system on save. The manual field only appears when an administrator switches the firm to *Manual* under *Sales Communication → Sample Delivery Note → Sample Delivery Number*. See [Sample delivery numbering](#sample-delivery-numbering).

### It says the sample delivery number is already in use.

Sample delivery numbers are unique across the firm, so the one you typed belongs to another entry. Type a different one. If the firm is on automatic numbering and you keep hitting this, the counter was probably reset back to a range already used — an administrator should raise it on the *Reset Numbering* tab.

### How do I change the wording on the printed note?

That lives in the firm template, not on this page. See [Sample delivery note](/docs/settings/document-templates#sample-delivery-note) for the subject, opening paragraph, closing text, terms, and tokens.

### Someone deleted a delivered sample — what happened to the stock?

Deleting a delivered (or partially/fully returned) sample re-adds any quantity that was still out, because the outbound movement disappears with the record. A snapshot is kept for audit, but the action itself can't be undone, so *Delete Sample Delivery* should be a restricted permission.