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

# Shops Creator - Events

> Server events other resources can listen for

Shops Creator emits server events so other resources can **react** to shop activity, phones, banking, MDTs, tax or loan systems, analytics, without editing the resource. To **read** shop state on demand, see the [Server Exports](/docs/shops-creator/exports/server).

Listen for any event with a standard handler:

```lua theme={null}
AddEventHandler('lation_shops:purchase', function(data)
    print(('Shop %s sold %d item lines for %d'):format(data.shopId, #data.items, data.total))
end)
```

<Warning>
  Every event fires **after** the change is committed. The event runtime isolates a **throwing** handler, so a listener that errors never breaks the shop. It does **not** isolate latency: events are dispatched synchronously, and `purchase`, `sale`, `deposit` and `withdraw` fire inside a per-player money lock. A slow handler serializes that player's transactions behind your code, so keep handlers fast and offload heavy work (a timer, a queue, an async call).
</Warning>

### **lation\_shops:purchase**

A customer bought items from a shop (fired after payment is taken, items are granted and revenue is credited).

```lua theme={null}
{
  shopId        = "market_247",
  source        = 12,                 -- buyer server id
  identifier    = "char1:abc...",
  name          = "John Doe",
  items         = { { item = "water", quantity = 2, price = 5 } },
  total         = 10,                 -- amount the customer paid
  paymentMethod = "cash",
  shopRevenue   = 8,                  -- credited to the shop after shares/commission
}
```

<Note>
  `shopRevenue` is the intended credit. In the rare event the credit write fails, the purchase still completes and the value reflects intent, not confirmation.
</Note>

### **lation\_shops:sale**

A customer sold items back to a shop (fired after the payout).

```lua theme={null}
{
  shopId        = "market_247",
  source        = 12,                 -- seller server id
  identifier    = "char1:abc...",
  name          = "John Doe",
  items         = { { item = "water", quantity = 2, price = 3 } },
  total         = 6,                  -- amount paid to the seller
  paymentSource = "shop",             -- where the payout came from
}
```

### **lation\_shops:ownerChanged**

A shop changed hands. Fires on every ownership path, identified by `reason`.

```lua theme={null}
{
  shopId             = "market_247",
  reason             = "purchase",    -- see below
  ownerIdentifier    = "char1:abc...", -- nil when the shop became unowned
  ownerName          = "John Doe",
  previousIdentifier = nil,           -- previous owner, when known
  previousName       = nil,
  source             = 12,            -- actor server id, when applicable
}
```

| `reason`      | Meaning                                     |
| ------------- | ------------------------------------------- |
| `purchase`    | A player bought a for-sale shop             |
| `abandon`     | The owner abandoned the shop                |
| `transfer`    | Ownership was transferred to another player |
| `adminAssign` | An admin assigned the owner                 |
| `adminRemove` | An admin repossessed the shop               |

<Note>
  When a shop changes hands, its staff are wiped **without** a per-employee event. Treat `ownerChanged` as a full staff reset.
</Note>

### **lation\_shops:employeeChanged**

A shop's staff changed, identified by `action`.

```lua theme={null}
{
  shopId     = "market_247",
  action     = "hired",              -- 'hired' | 'fired' | 'updated' | 'compensation'
  identifier = "char1:def...",
  name       = "Jane Roe",
  source     = 12,                   -- actor server id
}
```

`updated` is a role or permission change; `compensation` is a commission change.

### **lation\_shops:balanceChanged**

A shop's balance moved. This is a catch-all: **every** balance movement emits exactly one event, so it fires alongside the richer events above (for example, a purchase emits both `purchase` and `balanceChanged`).

```lua theme={null}
{
  shopId  = "market_247",
  delta   = 8,                       -- signed change; present for relative moves
  balance = nil,                     -- absolute value; present for direct sets instead of delta
  reason  = "sale_revenue",          -- tag when the caller supplies one, else nil
}
```

Common `reason` tags: `sale_revenue`, `deposit`, `withdraw`, `stock_order`, `purchase_reset`. Moves without a tag carry `reason = nil`.

### **lation\_shops:orderPlaced**

A restock order was placed (manual or auto-restock).

```lua theme={null}
{
  shopId     = "market_247",
  orderId    = 4821,
  items      = { { item = "water", label = "Water", quantity = 50, wholesaleEach = 2 } },
  totalCost  = 100,
  identifier = "char1:abc...",       -- nil for auto-restock
  name       = "John Doe",
}
```

### **lation\_shops:orderDelivered**

A restock order was delivered and its stock applied.

```lua theme={null}
{
  shopId  = "market_247",
  orderId = 4821,
  items   = { { item = "water", label = "Water", quantity = 50, wholesaleEach = 2 } },
}
```

<Note>
  Want an event we don't emit yet? Contact us and we'll do what we can!
</Note>