> ## Documentation Index
> Fetch the complete documentation index at: https://www.twicecommerce.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Settings - Item fulfillment states

> Name the states your staff move order items through, and set where a new item lands.

export const viewAccessDefinition = "The view operation: read a record without changing it.";

export const manageAccessDefinition = "The manage operation: update an existing record. Creating and deleting are separate operations.";

export const deleteAccessDefinition = "The delete operation: remove a record. Most areas archive instead of deleting.";

export const createAccessDefinition = "The create operation: add a new record. Updating an existing one is the manage operation.";

<Info>
  This view can look different dependent on your user role. <br />See [Visibility and permissions](#visibility-and-permissions) for details.
</Info>

## Primary purpose

Item fulfillment states are yours to define. Open **Settings → Orders → Item fulfillment states** to rename the six states your account starts with, add your own, recolour them, reorder them, and delete the ones your staff never use.

Every state belongs to one of four **fulfillment groups**. The group is what the platform reads: which stock a state claims, whether the item counts as a return, whether an order automation may move it. The state is the name your staff see on the item.

<AccordionGroup>
  <Accordion title="The four fulfillment groups">
    A state's group is fixed when you create it, so decide the group first and the name second.

    | Group          | What an item in it means                                                                      |
    | :------------- | :-------------------------------------------------------------------------------------------- |
    | **Preparing**  | Stock is reserved for the period. The item is at your premises.                               |
    | **Handed out** | Handed out to customer. A sale unit also leaves your stock.                                   |
    | **Returned**   | Item is no longer with customer. The item's end date can be updated to match the return time. |
    | **Removed**    | Item is excluded from the order. Any assigned stock items are cleared and freed.              |

    Order automations move items down this list and never back up it, which is why the settings page lists the groups in this order.
  </Accordion>

  <Accordion title="The six states your account starts with">
    | State            | Group      | Notes                                                                         |
    | :--------------- | :--------- | :---------------------------------------------------------------------------- |
    | **Pre-assigned** | Preparing  | A unit is picked automatically and can still be swapped. Sits behind **More** |
    | **Assigned**     | Preparing  | A unit is committed to the order, not yet collected                           |
    | **On Hold**      | Preparing  | Order automations leave it alone. Sits behind **More**                        |
    | **Handed Out**   | Handed out | The handover itself                                                           |
    | **Returned**     | Returned   | Counts as a return in your reports                                            |
    | **Excluded**     | Removed    | Takes the item off the order. Sits behind **More**                            |

    These are the states the product carried before you could define your own, so a new account opens on a list your staff already know. Being a seeded state only fixes the name: rename one and it keeps your wording from then on, in every language.

    Nothing seeds a not-returned state. A merchant who writes items off adds one under **Returned** and sets its return condition.
  </Accordion>

  <Accordion title="What you set on a state">
    Each state carries a **Name**, a **Key**, a **Description** and a colour. The key is what the API addresses the state by. Left empty it is built from the name, and it cannot change afterwards.

    Turn on **Secondary state** to keep a state out of the main picker, behind a **More** entry. Use it for states staff need now and then rather than on every item.

    The rest of the form depends on the group:

    | Group     | Setting                           | What it does                                                                                     |
    | :-------- | :-------------------------------- | :----------------------------------------------------------------------------------------------- |
    | Preparing | **Allow auto-switch**             | The unit can be switched to another overlapping order, and the system picks another suitable one |
    | Preparing | **Hide the assigned unit**        | Staff do not see the auto-picked unit and bind one by hand                                       |
    | Preparing | **Exclude from automation flows** | Order automations never move an item out of this state                                           |
    | Returned  | **Return condition**              | Whether the item came back, or did not: lost, damaged or kept                                    |

    Only items in a returned-by-the-customer state count in return reports. The reports read the setting live, so switching it back corrects the figures again, items in the state or not.
  </Accordion>

  <Accordion title="Where a new item lands">
    **New item automations**, below the states, answers one question per rule: which state an item lands in when it is added to an order.

    | Rule                                  | Fires when                        |
    | :------------------------------------ | :-------------------------------- |
    | **When a unit is auto-assigned**      | The platform picks the unit       |
    | **When staff assign a specific unit** | Someone scans or chooses the unit |

    Both rules are required and both may only target a **Preparing** or a **Handed out** state. A new item has to land somewhere, and it cannot arrive already returned or removed.

    Set an answer per [purchase type](/docs/concepts/orders/order-types) on its own tab. A line whose purchase type has no tab of its own follows the shared answer.
  </Accordion>

  <Accordion title="Show fulfillment states in order">
    The last card lists your locations. Untick the ones where staff never touch item states, and the order view there hides the state column, the state pickers and the fulfil actions.

    The platform behaves the same either way. Items still move in the background under your [order lifecycle](/docs/settings/orders/order-lifecycle) automations, and staff can always mark an item as removed.
  </Accordion>

  <Accordion title="Deleting a state">
    A state that a rule points at cannot be deleted. Repoint the rule first, because retargeting it changes what happens to future orders. The dialog names the rule standing in the way, whether it is a new-item rule or an order automation.

    A state holding items asks you where those items go, and offers the other states of the same group. TWICE never guesses: moving a "Lost" state's items into **Returned** would turn historical write-offs into returns, and past orders and reports read the new state from then on.

    Where a group has no other state to move them to, the items keep the group and lose the state. The dialog says what they will read as before you confirm.

    **Removed** keeps a minimum of one state, because taking an item off an order needs somewhere to put it.
  </Accordion>
</AccordionGroup>

## Related concepts

<AccordionGroup>
  <Accordion title="Groups, not states, are what the platform reads">
    Availability, utilisation reports, return counts and the order's own fulfillment chip all read an item's group. None of them reads a state's name. So your states can say whatever your staff need them to say, and nothing downstream changes meaning.

    Read more: [Order Lifecycle](/docs/concepts/orders/order-lifecycle)
  </Accordion>

  <Accordion title="What holds a stock item">
    An item in **Preparing** or **Handed out** claims its unit for the order's period. A **Returned** or **Removed** item does not. The claim is bounded by the booked period, so a state can never keep a unit out of stock indefinitely. Take a lost unit out of use on the inventory side instead.

    Read more: [Stock Item State](/docs/concepts/inventory/stock-item-state)
  </Accordion>

  <Accordion title="Order moves are what fire these states">
    The rules on this page cover items arriving on an order. What happens to an order's items when the order itself moves on is set under **Order lifecycle**.

    Read more: [Order lifecycle](/docs/settings/orders/order-lifecycle)
  </Accordion>
</AccordionGroup>

## Visibility and permissions

This page is gated by `account_settings:orders`, in the four operations <Tooltip tip={viewAccessDefinition}>view</Tooltip>, <Tooltip tip={createAccessDefinition}>create</Tooltip>, <Tooltip tip={manageAccessDefinition}>manage</Tooltip> and <Tooltip tip={deleteAccessDefinition}>delete</Tooltip>.

Owner and Admin hold every operation. Manager and Member do not hold it at all. Every order screen reads the state list under `orders:order:view` instead, so staff who cannot open this page still see the states your account defines.

For what each operation means and the full role matrix, see [Users & Roles](/docs/settings/users-roles).

## Related articles

<CardGroup cols={2} className="doc-rows-condensed">
  <Card title="Orders settings" href="/docs/settings/orders">
    The three sections under Settings → Orders.
  </Card>

  <Card title="Order lifecycle" href="/docs/settings/orders/order-lifecycle">
    The states an order moves through, and what is checked along the way.
  </Card>

  <Card title="Order Lifecycle" href="/docs/concepts/orders/order-lifecycle">
    How the order's own chips are derived from its items.
  </Card>

  <Card title="Auto-Fulfillment" href="/docs/concepts/orders/auto-fulfillment">
    How the platform picks a unit for an incoming order.
  </Card>
</CardGroup>