# Sales job items

An item row records one product or service in a sales job. Use the row to carry the
description, quantity, unit, and—at offer and order stages—commercial values through the
sales flow.

## Sales job items

The same sales-job workspace carries item grids for the inquiry, offer, and order panels,
so item work stays with the record as the opportunity develops.

The main path is `Potential` → `Inquiry` → `Offer Preparation` → `Offer` → `Order`.
After the order is ready, delivery moves the work toward `Delivered`, then the delivered
values continue to Sales Invoice and Incoming Client Payment. An order can also hand item
work to BOM when the companion manufacturing work is needed.

```mermaid
flowchart LR
    Potential --> Inquiry
    Inquiry --> OfferPreparation[Offer preparation]
    OfferPreparation --> Offer
    Offer --> Order
    Order --> Delivery
    Delivery --> Delivered
    Delivered --> SalesInvoice[Sales Invoice]
    SalesInvoice --> IncomingClientPayment[Incoming Client Payment]
    Order --> BOM
```

Use this page according to the work you need to complete:

| If you need to… | Go to |
|---|---|
| Check access, stage, required data, or company-configured limits | [Before you start](#before-you-start) |
| Open the saved job and its item panel | [Find and open the sales job](#find-and-open-the-sales-job) |
| Identify the fields in the current panel | [Understand the item surface](#understand-the-item-surface) |
| Add descriptions, units, and quantities | [Add item rows](#add-item-rows) |
| Enter prices, discounts, tax, and delivery values | [Price the item and review delivery details](#price-the-item-and-review-delivery-details) |
| Apply **Unitized** or **Package** treatment | [Use Unitized and Packages lines](#use-unitized-and-packages-lines) |
| Check why a stage action or row operation is unavailable | [Handle item branches and locks](#handle-item-branches-and-locks) |
| Follow delivery into invoicing and payment | [Follow item values into delivery and invoices](#follow-item-values-into-delivery-and-invoices) |
| Save changes or correct a validation message | [Save the item changes and resolve validation errors](#save-the-item-changes-and-resolve-validation-errors) |
| Continue with the wider sales-job process | [Continue the sales job](#continue-the-sales-job) |
| Understand the complete sales-job record | [Sales job record](https://pams-doc-test-fresh.atloria.app/p/pams-doc-test-fresh-N9B4TwWn3Q/user/sales-job-record) |
| Prepare shared sales-job information | [Sales job information and assessment](https://pams-doc-test-fresh.atloria.app/p/pams-doc-test-fresh-N9B4TwWn3Q/user/sales-job-information-and-assessment) |
| Follow stage changes and hand-offs | [Sales job lifecycle](https://pams-doc-test-fresh.atloria.app/p/pams-doc-test-fresh-N9B4TwWn3Q/user/sales-jobs-lifecycle) |
| Move an order through delivery | [From orders to delivered](https://pams-doc-test-fresh.atloria.app/p/pams-doc-test-fresh-N9B4TwWn3Q/user/from-orders-to-delivered) |
| Create or review invoices and payments | [Invoice lifecycle](https://pams-doc-test-fresh.atloria.app/p/pams-doc-test-fresh-N9B4TwWn3Q/user/invoice-lifecycle) |
| Work with BOM or warehouse fulfilment | [Warehouse fulfillment flow](https://pams-doc-test-fresh.atloria.app/p/pams-doc-test-fresh-N9B4TwWn3Q/user/warehouse-fulfillment-flow) |

## Before you start

An item grid is the working area for changing rows, but the available changes depend on
the record, your access, the current stage, and company configuration.

**Prerequisites**

- Open a saved sales job when you need to change an existing record.
- Have edit access to the sales job.
- Confirm that the current stage permits the intended item change.
- Have the product description, unit, quantity, and commercial values needed for the row.
- Know that **Item Description** is required.
- Check the configured quantity and item-price limits used by your company.

The grid is read-only when the screen is opened with a passed-in record ID or when your
user cannot edit. Inquiry item editing is also blocked after the inquiry leaves its initial
stage. The inquiry panel hides the package/unitized switch, so those row treatments are
not available there.

| Before changing rows, check… | Why it matters |
|---|---|
| The record is saved | Existing-record item work is performed on the saved sales job. |
| Your edit access | Without edit access, the item grid is read-only. |
| The current stage | Inquiry rows can no longer be edited after the inquiry leaves its initial stage. |
| Product description | **Item Description** is required for an item row. |
| Company limits | Quantity and item-price limits come from configuration. |

**Result:** You know whether the current item grid can be changed and have the product,
unit, quantity, and commercial details ready for the row.

## Find and open the sales job

The **Sales jobs** work list groups sales jobs by their current work stage. Open a saved
row from the list, then select the stage summary that contains the item panel you need.

**Prerequisites**

- Know which saved sales job you need.

**Steps**

1. Open the **Sales jobs** work list.
2. Select the list that matches the job's current stage.

   | If the job is… | Select |
   |---|---|
   | In any list or stage | **All** |
   | A potential | **Potentials** |
   | An inquiry | **Inquiries** |
   | An offer | **Offers** |
   | An order | **Orders** |
   | Archived | **Archived** |

3. Select the appropriate action for the row you need to work with.

   | If you need to… | Select |
   |---|---|
   | Start a new sales job | **Add new** |
   | Open a saved sales job | The sales-job data row |
   | Receive an inquiry from a potential | **Receive inquiry** |

4. Select the stage summary for the item work you need.
5. In the opened panel, locate its item grid and its panel-level **Save** control.

![Sales jobs work list with the stage tabs and item-work entry point](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/586c0cbaacccef78397dd14dfe66fe2f.png)

**Result:** The saved sales job is open at its selected stage panel, with the panel's item
grid and **Save** control visible when editing is permitted.

## Understand the item surface

An item grid shows the row values relevant to the current sales stage. Inquiry work starts
with product identity and quantity; offer and order work adds commercial values.

| Panel | Item columns |
|---|---|
| Inquiry | **Item Description**, **Unit**, **Qty** |
| Offer | **Item Description**, **Unit**, **Qty**, **Unit Price**, **Item Price**, **Discount limit (%)**, **Discount (%)**, **Tax (%)** |
| Order | **Item Description**, **Unit**, **Qty**, **Unit Price**, **Item Price**, **Discount limit (%)**, **Discount (%)**, **Tax (%)** |
| Delivery dialog | **Delivery Date** |

The inquiry surface also shows the sales-job information fields enabled in the saved
settings. Use the headers visible in the current grid when you work. The **Category**
column is not part of the item grid shown on this screen.

![Inquiry item grid with Item Description, Unit, and Qty](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/f39b6955bf40334699f5364efab18afd.png)

**Result:** You can distinguish the identity and quantity fields used at Inquiry from the
pricing fields added at Offer and Order, and you know to work from the headers currently
shown.

## Add item rows

An item row identifies the product or service that the sales job concerns and records the
amount requested or sold. Add the row only when the current grid exposes the **+ Item**
action.

**Prerequisites**

- Have an editable item grid open.
- Have the product or service to select in **Item Description**.

**Steps**

1. In the item grid, select **+ Item**.
2. In the new row, select the product or service in **Item Description**.
3. In **Unit**, select the unit when the field is enabled.
4. In **Qty**, enter a quantity of at least `0.1` when the field is enabled.
5. Repeat the row-entry steps for each additional item row.

**Item Description** is a required product autocomplete. **Unit** is disabled for package
rows and when the selected product already has a unit value. **Qty** is disabled for
package rows, has a minimum of `0.1`, and uses the configured quantity limit as its
maximum. At Inquiry, the item grid shows **Item Description**, **Unit**, and **Qty**; the
offer and order price columns are not shown there.

![Item row with the required Item Description field](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/ffbb0b16f68accde19ec2202cb284d78.png)

**Result:** The grid contains item rows with a selected description and permitted unit and
quantity values.

## Price the item and review delivery details

Offer and order rows carry the commercial values used to review and deliver the sale.
Enter only values allowed by the row treatment and by the configured limits.

**Prerequisites**

- Open an editable Offer or Order panel when entering price values.
- Have the agreed prices, discounts, tax, delivery information, and payment information.

**Steps**

1. In an Offer or Order item row, enter a non-negative **Unit Price** when the field is enabled.
2. Enter a non-negative **Item Price** when the field is enabled.
3. Review the read-only **Discount limit (%)**.
4. Enter **Discount (%)** from `0` through `100` when the field is enabled.
5. Enter **Tax (%)** from `0` through `100`.
6. Enter **Delivery Time** and select **Delivery Term** when the saved settings require them.
7. In the Offer or Order panel, review **Payment Method** and **Payment Period**.
8. When delivery is opened, enter the required **Delivery Date** no later than today.

**Unit Price** is disabled for packages, has a minimum of `0`, and uses the configured
item-price limit as its maximum. **Item Price** is disabled for unitized items, has a
minimum of `0`, and uses the configured item-price limit as its maximum. **Discount limit
(%)** is read-only and disabled for packages. **Discount (%)** is disabled for packages
and accepts `0` through `100`. **Tax (%)** accepts `0` through `100`.

**Delivery Time** and **Delivery Term** become required when the saved settings require
them. **Delivery Date** is required and cannot be later than today. A later date is
rejected because delivery is being recorded against the current date.

**Result:** The current offer or order row contains the permitted commercial values, and
the delivery information is ready for the delivery action.

### Use Unitized and Packages lines

**Package** applies package treatment to selected rows. **Unitized** applies unitized
treatment to selected rows. These treatments change which row fields remain editable.

**Prerequisites**

- Select the rows that need the same treatment.
- Work in a panel where the package/unitized switch is visible.
- Confirm that the selected rows allow the action.

**Steps**

1. Select the rows to treat.
2. Select the treatment that applies to the selected rows.

   | If the rows must use… | Select |
   |---|---|
   | Package treatment | **Package** |
   | Unitized treatment | **Unitized** |

3. Review the row fields that become disabled after the treatment is applied.

| Treatment | Fields that become unavailable |
|---|---|
| **Package** | **Unit** and **Qty** |
| **Unitized** | **Item Price** |

The **Package** and **Unitized** actions appear only when the switch is not hidden and the
selected rows allow that action. The inquiry item panel hides the switch, so use these
actions only in a panel where the controls are present.

**Result:** The selected rows use the available treatment, and the locked fields match the
treatment shown in the grid.

## Handle item branches and locks

Stage actions are guarded by the sales-job state, branch relationship, supplier context,
permissions, and whether the current record still has unsaved changes. A missing action
means the current record does not meet that action's conditions.

| Action | Available when… |
|---|---|
| **Calculation Sheet** in Offer | An offer exists, supplier context is present, the applicable margin mode is active, and the offer has no unsaved changes. |
| **Calculation Sheet** in Order | An order exists, supplier context is present, the applicable margin mode is active, and the order has no unsaved changes. |
| **Request Pricing** | The offer is a draft in the applicable offer stage and prices have not already been released or requested. |
| **Request Pricing Confirmation** | The order is a draft and prices have not already been released or requested. |
| **Deliver Order** | The order is in the relevant valid or ready-for-shipment stage and the branch relationship is valid. |
| **Split** | One edited row is selected. |
| **Delete** | Row deletion is allowed. |

The item grid is read-only when the record or your user is not editable. Do not use **Save**
as a workaround for a stage or permission lock: the row remains unchanged until the
condition that controls the lock is satisfied.

**Result:** You can choose the action that belongs to the current stage without attempting
an action blocked by state, branch, permission, selection, or unsaved changes.

## Follow item values into delivery and invoices

Delivery completes the order side of item work. When delivery covers all active orders,
the sales job reaches **Delivered**; external-supplier delivery can also create a draft
invoice for the delivered item work.

**Prerequisites**

- Have an eligible order with item values saved.
- Confirm that the order meets the conditions for **Deliver Order**.
- Have the delivery date ready.

**Steps**

1. Open the eligible order panel.
2. Select **Deliver Order**.
3. Enter the required **Delivery Date** in the delivery dialog.
4. Complete the delivery action exposed by the dialog.
5. Open the **Invoices** tab when the delivery result directs you there.
6. Review the draft invoice created from active, offered, ordered, or ready-for-shipment items when the delivery uses an external supplier.

Delivery changes the job stage to **Delivered** only when delivered orders equal active
orders. The delivery success message directs you to the **Invoices** tab for a draft
invoice. The **Invoices** tab is available only when the invoice feature is enabled, and
its contents are provided by the invoice list. The tab's plus action is available only
when the invoice feature is enabled, the **Invoices** tab is active, you have same-branch
access, and you have permission to create an additional invoice.

Delivery is the hand-off to `Sales Invoice`, which in turn leads to `Incoming Client
Payment`. Detailed order-to-delivery work belongs in [From orders to delivered](https://pams-doc-test-fresh.atloria.app/p/pams-doc-test-fresh-N9B4TwWn3Q/user/from-orders-to-delivered);
invoice creation and payment work belongs in [Invoice lifecycle](https://pams-doc-test-fresh.atloria.app/p/pams-doc-test-fresh-N9B4TwWn3Q/user/invoice-lifecycle).

**Result:** The order is delivered when all active orders are delivered, and any draft
invoice created by external-supplier delivery is available from **Invoices**.

## Save the item changes and resolve validation errors

**Save** commits the changed item values for the current panel. Correct the row or the
related panel data when a validation message stops the save.

**Prerequisites**

- Complete the permitted item fields for the current stage.
- Leave at least one item row when deleting.
- Save an opened cost sheet before saving the related sales-job change.
- If approval is enabled, follow the configured approval process before relying on the changed offer or order.

> **Note:** Approval responsibility follows your configured approval process.

**Steps**

1. Select **Save** in the panel after entering valid item values.

   | Panel | Select |
   |---|---|
   | Offer | **Save** |
   | Order | **Save** |

2. If **Item Description** is required, select a product or service in **Item Description**.
3. If **Qty** or **Unit** is invalid, enter a permitted quantity or select an available unit.
4. Read the validation message.
5. Select the invalid price, discount, tax, or delivery value. Replace it with a permitted value.
6. If deleting a row, read the confirmation before confirming the deletion.
7. Select **Save** again after all required corrections are complete.

The item and sales-job messages are:

| When it appears | Message | Correction |
|---|---|---|
| A required item or delivery date is empty | `This field is required` | Complete the required field. |
| A quantity is outside its permitted range | `Invalid input. The value must be greater than 0 and cannot exceed 999,999.00` | Enter a value greater than `0` within the configured limit. |
| A price or tax is negative | `Invalid input. Please enter a non-negative value` | Enter `0` or a positive value. |
| You select item deletion | `Are you sure you want to delete this item?` | Confirm only when the row should be removed. |
| Deletion would remove every row | `You can not delete all items, leave one item at least` | Keep at least one item row. |
| An item has zero quantity | `One or more items has ZERO quantity` | Enter a permitted quantity. |
| An item has no unit | `One or more items has no unit` | Select a unit where the field is enabled. |
| An opened cost sheet is not saved | `Please save opened cost sheet first` | Save the cost sheet, then save the sales job. |
| The margin blocks released prices | `The gross profit margin is unacceptable, and the release prices have been stopped.` | Review the permitted prices and margin configuration. |

Other messages recorded for sales-job actions are shown exactly below:

- Conversion to an offer: `Converted to offer successfully`.
- Conversion to an inquiry: `Converted to inquiry successfully`.
- Regret conversion: `Converted To Regretted`.
- Cancellation conversion: `Converted to cancelled`.
- Lost conversion: `Converted to lost`.
- Save or action failure: `An error occurred while processing your request`.
- Custom-field save failure: `Error saving custom fields`.
- Delivery reversal blocked by an invoice: `Cannot be un-delivered — a due invoice already exists`.
- Return to inquiry blocked: `All offers must be in draft status to revert to inquiry`.
- Dynamic action failure: `Error {{errorMsg}}`.
- Duplicate account name: `An account with this name already exists`.
- Duplicate project name: `A project with this name already exists`.
- Mandatory sales-job data missing: `Check mandatory field(s)`.
- Open inquiry not saved: `Please save opened inquiry first`.
- Return to potential blocked: `All inquiries must be in draft stage to revert to potential`.
- Payment milestone action missing: `Please enter action for each milstone`.
- Cost calculation save failure: `An error occurred while processing your request`.
- Cost calculation validation failure: `Check mandatory field(s)`.
- Discount exceeds negotiation margin: `There is a maximum discount that exceeds the negotiation margin.`
- Custom fields saved: `Custom fields saved successfully`.
- Sales job updated: `Job updated successfully`.
- Sales job deleted: `Job deleted successfully`.
- Sales job regretted: `Job regretted successfully`.
- Sales job cancelled: `Job cancelled successfully`.
- Sales job missed: `Job missed successfully`.
- Sales job reactivated: `Job reactivated successfully`.

**Result:** The changed offer or order is saved when every required value is valid; when
the save stops, the displayed message identifies the correction to make before retrying.

## Continue the sales job

Item work belongs to the wider lifecycle of **Potentials**, **Inquiries**, **Offers**,
**Orders**, and **Delivered**. The sales-job record connects item work with related record
areas,
so continue from the focused page that owns the next task instead of repeating its
procedure here.

| Next task | Open |
|---|---|
| Create a standard new job, a potential, a direct order, or an instant job | [Create a sales job](https://pams-doc-test-fresh.atloria.app/p/pams-doc-test-fresh-N9B4TwWn3Q/user/create-sales-job) |
| Follow lifecycle stages and transitions | [Sales job lifecycle](https://pams-doc-test-fresh.atloria.app/p/pams-doc-test-fresh-N9B4TwWn3Q/user/sales-jobs-lifecycle) |
| Work on the record and its related record areas | [Sales job record](https://pams-doc-test-fresh.atloria.app/p/pams-doc-test-fresh-N9B4TwWn3Q/user/sales-job-record) |
| Complete shared sales-job information and assessment | [Sales job information and assessment](https://pams-doc-test-fresh.atloria.app/p/pams-doc-test-fresh-N9B4TwWn3Q/user/sales-job-information-and-assessment) |
| Add comments and tasks | [Comments and tasks on a sales job](https://pams-doc-test-fresh.atloria.app/p/pams-doc-test-fresh-N9B4TwWn3Q/user/sales-job-comments-and-tasks) |
| Manage activities and attachments | [Activities and attachments on a sales job](https://pams-doc-test-fresh.atloria.app/p/pams-doc-test-fresh-N9B4TwWn3Q/user/sales-job-activities-and-files) |
| Review contacts, L/Gs, and history | [Contacts, L/Gs, and Last Modifications on a sales job](https://pams-doc-test-fresh.atloria.app/p/pams-doc-test-fresh-N9B4TwWn3Q/user/sales-job-contacts-guarantees-and-history) |
| Complete delivery and warehouse work | [Warehouse fulfillment flow](https://pams-doc-test-fresh.atloria.app/p/pams-doc-test-fresh-N9B4TwWn3Q/user/warehouse-fulfillment-flow) |

**Result:** The saved item values remain with the sales job, and you know which focused
sales-job page owns the next stage, delivery, invoice, or companion task.
