# Margin items

A margin item is a sales configuration definition that describes an item, selects its
margin basis, and sets a default percentage.

## Margin items at a glance

The list is headed **Mark up items**. It contains saved margin-item definitions and
opens the same fields for new and existing entries.

| If you need to… | Go to |
|---|---|
| Open the list | [Find Margin items](#find-margin-items) |
| Open a blank definition | [Open the list or a new item](#open-the-list-or-a-new-item) |
| Identify the fields | [List fields](#list-fields) |
| Enter or change a definition | [Add or edit a definition](#add-or-edit-a-definition) |
| Leave without saving | [Close without saving](#close-without-saving) |
| Remove a saved definition | [Delete a definition](#delete-a-definition) |
| Resolve access or validation problems | [Handle access and validation branches](#handle-access-and-validation-branches) |

![The Mark up items list with its visible columns and rows](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/b62f6f80cc439db882072770e143e246.png)

## Before you start

Your subscription and permissions determine which parts of the list you can use. The
account's developer mode also affects whether the description of a default item can be
changed.

| Condition | What you can see or do |
|---|---|
| The subscription includes the feature | The Margin items grid is shown. |
| The subscription does not include the feature | A subscription-upgrade surface is shown instead of the grid. |
| The new button is not hidden | **New** is shown when the feature is included. |
| You are allowed to edit | **Edit** is available for a row. |
| Delete permission is enabled | **Delete** is available from the open row menu. |
| Export permission and the export feature are available | **Export** opens the export choices. |
| The item is one of the two default item types and developer mode is off | **Item Description** is disabled. |

Have a saved row available before editing or deleting. A new definition uses **Item
Description**, **Ratio of**, and **Default (%)**.

## Find Margin items

Open the Margin items entry in the configuration area to reach the list.

### Prerequisites

- You have access to the Margin items feature.

### Steps

1. Open the Margin items entry in the configuration area.
2. Confirm that the page heading is **Mark up items**.
3. Confirm that **New** is visible when you need to create an entry.

**Result:**

The Margin items list is open under the **Mark up items** heading. Continue with [Open
the list or a new item](#open-the-list-or-a-new-item) or [Understand the list and form](#understand-the-list-and-form).

## Open the list or a new item

From the list, **New** opens an entry popup without changing saved data.

### Prerequisites

- The Margin items list is open.
- **New** is visible.

### Steps

1. Select **New**.
2. Confirm that the popup contains **Item Description**.
3. Select **Item Description**.

The new-entry form contains **Item Description**, **Ratio of**, and **Default (%)**.

![The new-entry popup with the three margin-item fields](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/99496ea9038d05cc32198c0043a6982b.png)

**Result:**

The new-entry popup is open and saved data is unchanged. Continue with [List fields](#list-fields)
or [Add or edit a definition](#add-or-edit-a-definition).

## Understand the list and form

The list shows saved definitions. The list displays **Item Description**, **Ratio of**,
and **Default (%)** as columns, with four rows. The entry form shows the same three
configured fields. Your list headers can differ because the list uses saved
list configuration.

The list also showed **Refresh** and **Settings** icon buttons. When the subscription
feature is unavailable, the subscription-upgrade surface replaces the grid.

![The entry fields with their required markers](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/99496ea9038d05cc32198c0043a6982b.png)

### List fields

| Field | Type and rule | Form | List |
|---|---|---|---|
| **Item Description** | Required text box | Yes | Visible column |
| **Ratio of** | Required select box; choices come from cost/margin lookup data | Yes | Visible in the list |
| **Default (%)** | Required percentage number box; value is restricted from 0 to 100 percent | Yes | Visible column |

Some system fields are hidden. You do not enter them, and they do not appear in the list.
An additional column can appear in the list without appearing in the form.

The **Ratio of** choices come from the cost/margin lookup, so use the choices shown on
your page. Column headers are hidden by the configuration, and paging is not configured
for this list. Continue with [Add or edit a definition](#add-or-edit-a-definition).

## Add, edit, and delete a margin item

Use the available action that matches the change you need.

| Need | Action and condition |
|---|---|
| Create a definition | Select **New** to open a new item. |
| Change a saved definition | Select **Edit** for the row when editing is allowed. |
| Remove a saved definition | Select **Delete** from the open row menu. |
| Commit a new or changed definition | Select **Save** after validation. |
| Choose an export option | Select **Export** when export permission and the export feature are available. |
| Change list order | Drag rows when drag and drop is enabled; the changed display order is saved. |

Continue with [Add or edit a definition](#add-or-edit-a-definition) for field entry, or
[Delete a definition](#delete-a-definition) for removal.

## Add or edit a definition

Use this procedure for a new margin item or for a saved row that you are allowed to edit.

### Prerequisites

- The Margin items list is open.
- **New** is visible for a new definition, or **Edit** is available for the selected row.
- You have the description, margin basis, and default percentage to enter.

### Steps

1. Select **New** for a new definition, or select **Edit** for the saved row.
2. Enter the item description in **Item Description**.
3. Select the applicable lookup value in **Ratio of**.
4. Enter a percentage from 0 through 100 in **Default (%)**.
5. Select **Save** after all required fields pass validation.

The form marks all three fields as required. If a required value is missing, the form can
show `Field is required`. If the percentage is outside
the allowed range, it can show `Range restricted from 0 - 100 %`.

After a successful new record, the page shows `Data saved Successfully`. After a
successful edit, it shows `Data updated Successfully`.

**Result:**

The popup is submitted after validation. Continue with [Close without saving](#close-without-saving)
if you opened the form without saving, or [Handle access and validation branches](#handle-access-and-validation-branches)
if validation prevents submission.

## Close without saving

Select **Cancel** when you do not want to commit the values in the entry popup.

### Prerequisites

- The new-entry popup is open.
- You do not need to save the values in the popup.

### Steps

1. Select **Cancel**.
2. Confirm that **Item Description** is no longer shown.

![The page state after the close attempt](https://atloriaassets.blob.core.windows.net/assets/a438221c-c1af-407c-b9e6-a56c986db846/3a63b2481aa749f68669c1e9f28a673a.png)

**Result:**

The close attempt completes without changing data and opens the Cancellation reasons
page. Continue with the [Cancellation reasons](https://pams-doc-test-fresh.atloria.app/p/pams-doc-test-fresh-N9B4TwWn3Q/user/configuration-sales-cancellation-reasons)
configuration page.

## Delete a definition

Deleting a definition requests removal of the selected row.

> **Caution:** Do not delete a default item, a row related to saved data, or the only item
> in the list.

### Prerequisites

- A saved row is selected.
- The row menu is open.
- Delete permission is enabled.

### Steps

1. Select **Delete** for the selected row.
2. Read the confirmation `Are you sure you want to delete this item?`.
3. Confirm the deletion only when the row meets the restrictions above.

After a successful deletion, the page shows `Data Deleted Successfully`.

| Message | Meaning at the delete request |
|---|---|
| `Default item` | The selected row is a default item. |
| `Related to Saved data, Can't be deleted` | Saved data is related to the row. |
| `Failed to Delete` | The deletion failed. |
| `Must have at least one item` | The list must retain at least one item. |

**Result:**

The selected row is submitted for deletion when the confirmation and restrictions permit
it. A successful deletion shows `Data Deleted Successfully`. Continue with [Handle access
and validation branches](#handle-access-and-validation-branches).

## Handle access and validation branches

Use the row that matches what you see on screen.

| What you see or encounter | What to do |
|---|---|
| The subscription-upgrade surface appears instead of the grid | Follow your subscription access requirements before maintaining Margin items. |
| **New** is absent | Check that the feature is included and that the new button is not hidden. |
| **Edit** is unavailable | Check that editing is allowed for the row. |
| **Delete** is unavailable | Check that delete permission is enabled and that the row menu is open. |
| **Export** is unavailable | Check export permission and the export feature. |
| **Item Description** is disabled for a default item | Use developer mode when the account is permitted to edit that default description. |
| A required field is empty | Complete the required field. The form can show `Field is required`. |
| **Default (%)** is outside the allowed range | Enter a value from 0 through 100. The form can show `Range restricted from 0 - 100 %`. |
| Forbidden characters are detected | Remove the forbidden characters, then select **Save**. The message is `Forbidden characters detected. Please remove them and try again.` |

**Result:**

The available fields and actions match the subscription, permissions, configuration, and
validation outcome. Continue with Cost items or Item units for related sales configuration.

## After maintaining the list

This page is a reference for the Margin items entity tab: its fields, its
maintenance actions, and the conditions that change those actions. The passing check
completed without changing data. Create, update, delete, reorder, import, and export
outcomes remain outside that check.

For the sibling sales configuration references, see Cost items and Item units. Import
upload and import confirmation belong to the shared configuration import flow; record
history filters and registration details belong to the record history surface; and
subscription-upgrade content belongs to the subscription access surface.
