Skip to main content
Stock item events timeline

Inventory > Stock Items > [Item] > Events

Definition

A Stock Item’s events record what the item is committed to and what has happened to it. TWICE Commerce distinguishes two layers:
  1. Scheduled events: time-ranged blocks (reservations and notes) created by you or by automation. A reservation blocks availability and a note does not.
  2. Activity events: the system-recorded history of changes to the item, such as its registration, edits, order assignments and location moves.
The stock item’s Events tab lists its scheduled events together with its orders and holds. The Activity log tab beside it is a separate record of the requests that changed the item: see Activity Logs.

Where do I use it?

Events are displayed in the Events tab of each Stock Item. You work with events when:
  • Tracking item availability: see what is blocking availability and when items will be free.
  • Following customer orders: every order that uses the item is listed on the tab automatically, with the dates it holds the item.
  • Managing internal reservations: block items for maintenance, storage, or internal use.
  • Adding documentation: record inspections, condition notes, repair logs, or important observations.
  • Auditing item history: the item’s Activity log tab shows who changed it and when. Read a stock item’s history walks through both tabs.

Scheduled events

Scheduled events are user-controlled and live on the article via scheduledEvents. Two types exist: Both types carry the same shape:
endDate can be null for open-ended events. A reservation with a null end date keeps the item unavailable until you give it an end date or delete it.

Reservations

Reservations create an unavailability range for the item. They are the way to take a Stock Item off the available pool for an internal reason, not a customer order, like maintenance, photo shoots, training, or holding an item for a known event.
  • Manually created from the Stock Item’s Events tab via Add → Reservation, which opens the Schedule a reservation drawer, or via POST /articles/:id/scheduled-events. An item with no events yet offers Reserve article in the empty state.
  • During the reservation range, the item drops out of ATS and cannot be assigned to new orders.
  • Once the end date passes, availability automatically returns. Reservations expire on their own, with no manual cleanup.
  • A reservation can carry an attachment via the article ledger (scheduledEventId on a ledger entry). For example, log the repair cost against the reservation that scheduled the work.
Prefer a reservation over Inactive when the unavailability has a known end date. Reservations expire automatically; Inactive requires manual reactivation. See Stock Item Status.

Reservation priority

A reservation you create takes precedence over existing holds (orders and other reservations) at its location when the stock item has no free capacity. TWICE Commerce resolves the conflict in order:
  1. Use any free capacity.
  2. Rearrange existing holds into other free slots at the same location where possible.
  3. As a last resort, release the fewest existing holds needed to make room.
Displaced orders and reservations are not cancelled. An order whose unit is already with the customer keeps the unit up to the reservation’s start, as though it came back then. Every other displaced order or reservation loses its hold on the unit.
A displaced order stays active and still names the unit, but nothing holds the unit for it, so the order shows a conflict. Open the unit on the order and click Claim unit again, or put another unit on the line. See Stock Item Conflicts.
Confirmation dialog showing affected orders when creating a conflicting reservation

Reservation conflict confirmation dialog

When holds must be released, the confirmation “Existing orders and reservations will be affected” opens before anything changes. It shows:
  • The reservation you are adding (name, dates, location).
  • A scrollable list of every order and reservation that will lose its hold on the stock item.
  • Each affected row can be expanded to load details: order number, customer, status, and dates for orders; name and comment for reservations.
  • A “Please confirm you understand the impact” checkbox gates the confirm button, Add reservation.
If the affected holds change between opening the dialog and confirming, for example because another order lands in the window, nothing is released and nothing is reserved. The notice reads Error creating reservation. Click Add again, and the dialog reopens with the current list.
Only holds at the same service location as the reservation are affected. Holds on other locations for the same stock item remain untouched.
Only creating a reservation takes holds. Editing one fits the new dates into a free unit at its location, moving other holds to other units where it can. When there is no room, the change is refused with Error updating reservation and the reservation keeps its old dates. Deleting a reservation frees its dates, but the holds it took when it was made do not come back. The orders it displaced keep their conflicts.

Notes

Notes are timestamped entries that do not block availability. Use them to document anything operational that should live on the item’s record but is not a real-time commitment.
  • Manually created from the Stock Item’s Events tab via Add → Note, which opens the Add a note drawer, or via POST /articles/:id/scheduled-events with type: 'note'.
  • Visible to operators with access to the item; never shown to customers.
  • Can have an endDate if the observation covers a range (e.g. “condition observed Jan 10–15”) or null for a single timestamp.
  • Useful as a base for incident reports, condition history, and operational handoffs.

Activity events

Everything that happens to a stock item is recorded as an activity event. These events are system-driven and not editable. The admin does not list them: the Events tab shows the item’s commitments, and the Activity log tab shows the requests that changed the item, with who made each one and when. Each row carries an eventType, a context object holding the ids involved, and a changes object holding what moved from what to what. The order the unit went out on is in context.references, so the event links back to it.
Handing a unit over and taking it back are not events on the unit. They are the item’s state on its order line moving between fulfillment groups, which the order’s own history records. Read a unit’s current commitment from Stock Item State, and define the states themselves under Fulfillment lifecycle.

Comparison

Where to manage events

Customer Orders

Manage orders. Orders automatically record events on assigned Stock Items.

Internal Reservations and Notes

Add and manage reservations and notes from the Stock Item’s Events tab.
The Events tab lists the item’s orders, reservations, notes and holds, latest start date first. The Activity log tab beside it lists who changed the item, and when.

Internal reservations vs holds

Reservations are the way to “hold” inventory in TWICE outside of an order. Common patterns:
  • Maintenance window. Block an item for a scheduled service period. Attach a ledger cost entry to the reservation for the repair invoice.
  • Photo shoot or training. Block an item without involving the orders system.
  • Operator hold. A customer is on the way to pick up: create a short-range reservation so no one else can book that item.
  • Damage assessment. Block the item until you have inspected and decided whether to return it to service.
Reservations cannot be converted into orders, because they are a separate flow. If a customer wants an item you have reserved, delete or shorten the reservation and create a real order.

Holds with no order or reservation

An unavailability is the hold that makes an item unavailable for a period. Most holds belong to an order or a reservation and end with it. The Events tab also lists two kinds that belong to neither:
  • Unavailability: a hold linked to no order and no reservation. It blocks the item until it ends, or for good when it has no end date.
  • Order (switched out): the hold a booking left on a unit when it moved to another unit.
Delete either from the Events tab while it is current or upcoming. A past hold stays as history, which the utilisation report reads. The hold an order currently uses changes when you edit the order.

Documents attached to events

Files can be attached to events through two mechanisms:
  1. Stock Item documents (documents on the article): global to the item.
  2. Article ledger entries with scheduledEventId: financial entries tied to a specific reservation. The ledger entry can reference a file attachment as part of its value payload.
For example: a Yearly service reservation drives a cost ledger entry of €150 with a PDF receipt attached. Both the reservation and the ledger entry stay linked, making the item’s audit trail traceable end to end.

Workflow triggers from events

Events are natural automation hooks. Common patterns:
  • On ARTICLE_ASSIGNED_TO_ORDER → tell your warehouse system to prepare the unit.
  • On ARTICLE_OVERBOOKING → alert whoever resolves conflicts, before the customer arrives.
  • On ARTICLE_LOCATION_TRANSFERRED → reconcile the receiving site’s count.
An order’s own events, rather than the unit’s, are what tell you a unit went out or came back. Subscribe to order.updated on a webhook to read those.

Lifecycle

1

Creation

Events are created automatically (activity events) or manually (reservations, notes).
Automatically, as the unit is registered, edited, moved and put behind orders. A unit joining an order records ARTICLE_ASSIGNED_TO_ORDER and leaving one records ARTICLE_UNASSIGNED_FROM_ORDER. What happens between those two is the item’s state on its order line, and the order records it.
2

Manual creation

Reservations and notes are added by hand from the Events tab.
On the stock item’s Events tab, choose Add → Reservation, and give the reservation a title, a location and dates in the Schedule a reservation drawer. If the item is at full capacity for the requested range, a confirmation dialog shows which existing holds will be released before the reservation is created. API: POST /articles/:id/scheduled-events with type: 'reservation'. Reserve a stock item walks through it.
Same flow as a reservation, but choose Add → Note and fill in the Add a note drawer. API: POST /articles/:id/scheduled-events with type: 'note'.
3

Automated creation

Yes. Use the API directly or trigger via workflows on customer order events, attribute changes, or external triggers.
4

Display

The Events tab lists the item’s orders, reservations, notes and holds.
On each stock item’s Events tab: Inventory → Stock items → [item] → Events. No table lists them across stock items.
By Start date, latest first. Click another column header to sort by it, or filter by dates, Reference, Comment or Has conflicts. The tab has no filter by event type. Read a stock item’s history walks through reading it.
Start date, End date, Event name, Reference, Created at, Comment, Location and Has conflicts. An order row can also show its Buffer time. Event name is a reservation’s or note’s title, and names the other rows by their kind.
5

Modification

Scheduled events are editable; activity events are not.
Not directly. An order row follows its order: change the order, and the row changes with it.
Yes. Click its row on the Events tab and save your changes in the Edit event drawer, or call PUT /articles/:id/scheduled-events/:eventId with the new fields. The new dates are fitted as described under Reservation priority. Edit a reservation walks through it.
Yes. Same endpoint as reservations.
6

Deletion

Scheduled events can be deleted; activity events cannot.
Tick the reservation’s row on the Events tab and click Delete above the table, or call DELETE /articles/:id/scheduled-events/:eventId. Tick several rows to delete them together. The dates are free at once. The income and expenses saved on the reservation are deleted with it. Delete a reservation walks through it.
Same as reservations.
No. They are the auditable history. Taking the unit off an order records ARTICLE_UNASSIGNED_FROM_ORDER, and the original ARTICLE_ASSIGNED_TO_ORDER stays in the log.

FAQs

Reservations are for internal blocks (maintenance, holds, photo shoots) without involving customers, payments, or order state. Orders are for customer-facing transactions.
No. They are separate entities. If a customer wants an item you reserved, delete the reservation and create a real order.
No. Notes are internal-only and never displayed to customers.
Yes. Documents on the Stock Item are always accessible from any event view. Article ledger entries can reference a specific scheduledEventId so financial attachments (invoices, receipts) stay associated with the reservation that triggered them.
Reservations and orders both block availability for the date range they cover. Notes do not. Activity events do not drive availability: they record what already happened.
No. Each stock item’s Events tab lists its own. To see which items are reserved and when, show the Next reservation column on Inventory → Stock items.
The tab lists only rows at the locations selected in the top-left corner of the admin, and an order row belongs to its pickup location. Select every location to see them all. An order that took another stock item of the same SKU is on that item’s tab, not this one.
When the unit was picked up and, if it came back, returned. Until then, the row shows the order line’s start and end, so an order nobody picked up shows the period it was meant to cover. Created at is when the unit was put on the order.
On an order row, the order still names this unit but nothing holds the unit for the order’s dates. Resolve it on the order: see Stock Item Conflicts. On a reservation row, the reservation has not ended and its hold could not be placed, so it does not block the dates it shows.
Affected orders are not cancelled. See Reservation priority for what they lose.
When a reservation releases a hold from an order, the affected stock item shows as unavailable on that order. The orders list displays a warning banner summarising the number of orders with conflicts, and the order’s Stock Items tab highlights the conflict with a red counter. Claim the unit again or assign a replacement stock item to resolve the conflict.

Developer Reference

Create and list scheduled events (reservations and notes) with the /articles/:id/scheduled-events endpoints. Activity log entries come from audit-logs.

API: Unavailability

Open the endpoint in the API reference.

Stock Items

Full Stock Item model and lifecycle

Stock Item State

How order events drive In/Out state

Stock Item Status

Why status changes are recorded as events

Workflows

Automate behaviour on events