Events - TWICE Commerce

Stock item events timeline — Inventory > Stock Items > [Item] > Events

Definition

A Stock Item’s events make up the timeline of everything that has happened to that item. TWICE distinguishes two layers:

Scheduled events — time-ranged blocks (reservations and notes) created by you or by automation. These can block availability and may carry attachments.
Activity log events — the system-recorded history of changes to the item (order assignment, fulfillment, status, location, attributes).

Together they answer the questions: what is this item doing right now? and what has happened to it?

Analogy: A Stock Item’s events are its calendar plus its diary. The calendar (scheduled events) is the forward-looking view of what is committed; the diary (activity log) is the auditable record of everything that has happened.

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.
Recording customer orders — order events are recorded automatically when items are assigned to orders.
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 — reconstruct exactly when and why an item changed state, status, location, or SKU.
Reporting — view all events across your inventory in one table.

Scheduled events

Scheduled events are user-controlled and live on the article via scheduledEvents. Two types exist:

Type	Blocks availability	Customer-facing	Created by
`reservation`	Yes	No	Operator (manual) or workflow
`note`	No	No	Operator (manual)

Both types carry the same shape:

{
  "id": "evt_abc123",
  "articleId": "art_xyz789",
  "type": "reservation",
  "name": "Yearly service",
  "comment": "Annual safety inspection",
  "startDate": "2025-06-01T08:00:00Z",
  "endDate": "2025-06-03T17:00:00Z",
  "serviceLocationId": "loc_helsinki",
  "tenantId": "tnt_001",
  "createdAt": "2025-05-15T12:00:00Z"
}

endDate can be null for open-ended events. Reservations with null end dates make the item unavailable until the reservation is closed.

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, or via POST /articles/:id/scheduled-events.
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 — no manual cleanup required.
A reservation can carry an attachment via the article ledger (scheduledEventId on a ledger entry) — e.g. log the repair cost against the reservation that scheduled the work.

Prefer a reservation over Out of use when the unavailability has a known end date. Reservations expire automatically; Out of use requires manual reactivation. See Stock Item Status.

Reservation priority

A manually-created reservation takes precedence over existing holds (orders and other reservations) when the stock item has no free capacity. TWICE first uses any free capacity, then rearranges existing holds into other free slots where possible, and only as a last resort releases the fewest existing holds needed to make room. Affected orders and reservations are not cancelled — only their hold on this specific stock item for the overlapping dates is released.

Releasing a hold means the affected order or reservation no longer reserves that stock item for the overlapping period. The order itself remains active, but the stock item becomes unassigned for that window. You may need to assign a replacement stock item to the affected order.

Confirmation dialog showing affected orders when creating a conflicting reservation — Reservation conflict confirmation dialog

When the system determines that holds must be released, a confirmation dialog appears before anything changes. The dialog 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.
An “I understand the impact” checkbox gates the confirm button.

If the set of affected holds changes between opening the dialog and confirming (for example, another operator adds a new order in between), TWICE asks you to review the updated list again before anything is released.

Only holds at the same service location as the reservation are affected. Holds on other locations for the same stock item remain untouched.

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, 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.

Order events (activity log)

When an item is assigned to a customer order, TWICE records a stream of events in the activity log. These events are system-driven and not editable. The full set of system event types:

`eventType`	When it fires	Context
`assigned_to_order`	Item is added to an order	`orderId`, `orderNumber`, `orderProductId`, `price`, `shopperId`
`freed_from_order`	Item is removed from an order or order is cancelled	Same as above
`handed_out`	Operator marks the line as picked up; state flips to Out	`orderId`, `orderNumber`, `shopperId`
`returned`	Operator marks the line as returned; state flips to In	`orderId`, `orderNumber`, `price`, `shopperId`, `orderProductId`
`allocation_changed`	The item’s rental vs sales allocation changed	`attributeChanges.from.allocation`, `attributeChanges.to.allocation`
`status_changed`	Status changed (e.g. In use → Out of use)	`attributeChanges.from.status`, `attributeChanges.to.status`
`sku_changed`	SKU link changed	`attributeChanges.from.sku`, `attributeChanges.to.sku`
`location_changed`	Service location changed	`attributeChanges.from.storeId`, `attributeChanges.to.storeId`
`identifiers_changed`	`codes` array was updated	`attributeChanges.from.itemCodes`, `attributeChanges.to.itemCodes`
`specifications_changed`	Attributes or fixed field values changed	`attributeChanges.from`, `attributeChanges.to`

Order events appear inline in the same Events timeline so you see both the commitments (reservations, notes) and the historical record together.

Comparison

Feature	Order event	Reservation	Note
Source	System	User or workflow	User
Where managed	Orders section	Stock Item Events tab	Stock Item Events tab
Blocks availability	Yes (while line is active)	Yes	No
Customer-facing	Yes	No	No
Time-based	Yes (rental or order period)	Yes (reservation period)	Optional (timestamp)
Expires automatically	Yes (on return / cancellation)	Yes (at `endDate`)	N/A
Carries attachments	Via the order itself	Via article ledger reference	Via article ledger reference
Common use cases	Customer rentals and sales	Maintenance, internal hold	Condition notes, incident logs

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 shows scheduled events and the activity log together in chronological order, giving you a complete picture of the item’s lifecycle.

Internal reservations vs holds

Reservations are the only 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 en route 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 — they are a separate flow. If a customer wants an item you have reserved, delete or shorten the reservation and create a real order.

Documents attached to events

Files can be attached to events through two mechanisms:

Stock Item documents (documents on the article) — global to the item.
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 handed_out → start a timer; flag the order as overdue if returned does not fire within N days.
On returned → create a maintenance reservation if the order line was tagged as damaged.
On status_changed to Lost → notify operations and open a ticket in your support system.
On reservation expiry → automatically set status back to In use after a repair window closes.
On assigned_to_order → write a webhook to your warehouse system to prepare the item.

Lifecycle

Creation

Events are created automatically (activity log) or manually (reservations, notes).

How are order events created?

Automatically when an item is assigned to a customer order. The events fire in this typical sequence: assigned_to_order → handed_out → returned. Cancellations record freed_from_order.

How do I create a reservation?

Open the Stock Item, go to Events, click Add reservation, set the start and end dates and an optional name/comment. 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'.

How do I create a note?

Same flow as a reservation, but choose Add note. API: POST /articles/:id/scheduled-events with type: 'note'.

Can event creation be automated?

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

Display

Events appear in chronological order on the Events tab.

Where do I see events?

Per-item: Inventory > Stock Items > [Item] > Events. Across all items: Inventory > Events.

How are events sorted?

Chronologically, most recent first. The UI lets you filter by event type and date range.

What is shown for each event?

For scheduled events: start date, end date, type, name, comment, location. For activity-log events: timestamp, event type, the before/after values (attributeChanges) or the order context (eventContext).

Modification

Scheduled events are editable; activity log entries are not.

Can I edit order events?

Not directly. They are a system audit log. Modify the underlying order — the activity log will record the new transitions.

Can I edit a reservation?

Yes. PUT /articles/:id/scheduled-events/:eventId with the new fields. Or click the reservation in the timeline and edit. Availability recalculates immediately.

Can I edit a note?

Yes. Same endpoint as reservations.

Deletion

Scheduled events can be deleted; activity log cannot.

How do I delete a reservation?

Click the reservation and choose Delete, or DELETE /articles/:id/scheduled-events/:eventId. The blocked availability is released immediately.

How do I delete a note?

Same as reservations.

Can I delete order events?

No — they are the auditable history. Cancelling the underlying order will record freed_from_order (and possibly returned if applicable) but the original assigned_to_order event stays in the log.

Bulk delete?

POST /articles/:id/scheduled-events/delete-many accepts either explicit ids or deleteAllExcept semantics.

FAQs

Why would I use a reservation instead of an order?

Reservations are for internal blocks (maintenance, holds, photo shoots) without involving customers, payments, or order state. Orders are for customer-facing transactions.

Can I convert a reservation to an order?

No. They are separate entities. If a customer wants an item you reserved, delete the reservation and create a real order.

Do notes appear to customers?

No. Notes are internal-only and never displayed to customers.

Can I attach documents to events?

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.

How do events affect availability calculations?

Reservations and orders both block availability for the date range they cover. Notes do not. Activity-log events do not directly drive availability — they record what already happened.

Can I see all events across all stock items?

Yes — Inventory > Events gives you a unified table. Filter by event type, create custom views, group by Stock Item, and export for reporting. For individual item history, use the Stock Item’s Events tab.

What happens if a reservation overlaps an order?

If a free capacity slot is available, the reservation takes it and the order is unaffected. If no free slot exists, TWICE attempts to reallocate existing holds to free slots non-destructively. Only when there is genuinely no room does the system ask you to confirm releasing the minimum set of existing holds. Affected orders are not cancelled — only their hold on that specific stock item is released. See Reservation priority for the full algorithm.

What are stock item conflicts on orders?

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. Assign a replacement stock item to resolve the conflict.

Developer Reference

Scheduled events (reservations and notes) are exposed as unavailabilities. 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

Welcome to TWICE Docs

Navigating in TWICE

Understand the system

Stock Item Events

Definition

Where do I use it?

Scheduled events

Reservations

Reservation priority

Notes

Order events (activity log)

Comparison

Where to manage events

Customer Orders

Internal Reservations and Notes

Internal reservations vs holds

Documents attached to events

Workflow triggers from events

Lifecycle

FAQs

Developer Reference

API: Unavailability

Stock Items

Stock Item State

Stock Item Status

Workflows

​Definition

​Where do I use it?

​Scheduled events

​Reservations

​Reservation priority

​Notes

​Order events (activity log)

​Comparison

​Where to manage events

Customer Orders

Internal Reservations and Notes

​Internal reservations vs holds

​Documents attached to events

​Workflow triggers from events

​Lifecycle

​FAQs

​Developer Reference

API: Unavailability

​Related Concepts

Stock Items

Stock Item State

Stock Item Status

Workflows

Definition

Where do I use it?

Scheduled events

Reservations

Reservation priority

Notes

Order events (activity log)

Comparison

Where to manage events

Internal reservations vs holds

Documents attached to events

Workflow triggers from events

Lifecycle

FAQs

Developer Reference

Related Concepts