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

# Webhook Events

> Reference for every storekit webhook event including order created, accepted, rejected, refunded, item out of stock, and payment status events with payloads.

This page lists all webhook events available in storekit, grouped by category.

## Order Events

Events related to order lifecycle and management.

| Event                       | Description                                               |
| --------------------------- | --------------------------------------------------------- |
| `order.created`             | Triggered when a new order is placed                      |
| `order.accepted`            | Triggered when an order is accepted by the store          |
| `order.rejected`            | Triggered when an order is rejected by the store          |
| `order.canceled`            | Triggered when an order is canceled                       |
| `order.preparing`           | Triggered when an order transitions to preparing status   |
| `order.ready_for_pickup`    | Triggered when an order is marked ready for pickup        |
| `order.out_for_delivery`    | Triggered when an order is dispatched for delivery        |
| `order.pos.dispatch.failed` | Triggered when an order fails to dispatch to a POS system |
| `order.rating.updated`      | Triggered when a customer updates their order rating      |
| `order.completed`           | Triggered when an order is marked as completed            |
| `order.refund.created`      | Triggered when a refund is issued for an order            |

### order.created

Triggered when a new order is placed by a customer.

```json theme={null}
{
  "event": "order.created",
  "data": {
    "id": "ord_abc123",
    "code": "A1B2",
    "asap": true,
    "total": 2500,
    "tip": 250,
    "deliveryFee": 299,
    "discountTotal": 0,
    "orderType": "Pickup",
    "createdAt": "2024-01-15T10:30:00Z",
    "deliveryTime": "2024-01-15T11:00:00Z",
    "notes": "Ring doorbell",
    "customer": {
      "firstName": "John",
      "lastName": "Doe",
      "email": "john@example.com",
      "phone": "+44123456789",
      "marketingConsent": true
    },
    "items": [
      {
        "name": "Margherita Pizza",
        "price": 1200,
        "quantity": 1,
        "plu": null,
        "posId": null,
        "taxRate": null,
        "modifiers": []
      }
    ],
    "venue": {
      "id": 1234,
      "name": "My Restaurant",
      "slug": "my-restaurant",
      "address": {
        "street1": "123 Main St",
        "street2": "",
        "city": "London",
        "postCode": "W1A 1AA",
        "country": "UK",
        "companyName": "My Restaurant Ltd",
        "coordinates": {
          "latitude": 51.5074,
          "longitude": -0.1278
        }
      }
    },
    "table": {
      "id": "tbl_123",
      "name": "Table 5",
      "covers": 4,
      "posId": "pos_tbl_5",
      "area": {
        "id": "area_1",
        "name": "Main Floor",
        "posId": null
      }
    },
    "deliveryAddress": {
      "street1": "456 Oak Ave",
      "street2": "Flat 2",
      "city": "London",
      "postCode": "E1 6AN",
      "country": "UK",
      "coordinates": {
        "latitude": 51.5155,
        "longitude": -0.0722
      }
    }
  }
}
```

### order.accepted

Triggered when an order is accepted by the store. Has the same payload structure as `order.created`.

### order.preparing

Triggered when an order transitions to the preparing status.

```json theme={null}
{
  "event": "order.preparing",
  "data": {
    "order": {
      "id": "ord_abc123",
      "code": "A1B2",
      "status": "preparing"
    },
    "venue": {
      "id": 1234,
      "name": "My Restaurant",
      "slug": "my-restaurant"
    }
  }
}
```

### order.ready\_for\_pickup

Triggered when an order is marked as ready for customer pickup.

```json theme={null}
{
  "event": "order.ready_for_pickup",
  "data": {
    "order": {
      "id": "ord_abc123",
      "code": "A1B2",
      "status": "ready_for_pickup"
    },
    "venue": {
      "id": 1234,
      "name": "My Restaurant",
      "slug": "my-restaurant"
    }
  }
}
```

### order.completed

Triggered when an order is marked as completed. This fires for individual order completions (via the dashboard, Deliverect, iKentoo, or auto-update) as well as bulk completions.

```json theme={null}
{
  "event": "order.completed",
  "data": {
    "order": {
      "id": "ord_abc123",
      "code": "A1B2",
      "status": "completed"
    },
    "venue": {
      "id": 1234,
      "name": "My Restaurant",
      "slug": "my-restaurant"
    }
  }
}
```

### order.pos.dispatch.failed

Triggered when an order fails to dispatch to a POS system.

```json theme={null}
{
  "event": "order.pos.dispatch.failed",
  "data": {
    "order": {
      "id": "ord_abc123",
      "code": "A1B2",
      "total": 2500
    },
    "venue": {
      "id": 1234,
      "name": "My Restaurant",
      "slug": "my-restaurant"
    },
    "pos": {
      "name": "Zonal",
      "error": "Connection timeout: Unable to reach POS endpoint"
    },
    "retryCount": 3
  }
}
```

***

## Store Events

Events related to store status and configuration.

| Event                         | Description                                                                  |
| ----------------------------- | ---------------------------------------------------------------------------- |
| `store.opened`                | Triggered when a store opens, a snooze ends early, or a timed snooze expires |
| `store.closed`                | Triggered when a store closes or is snoozed                                  |
| `store.opening_hours.updated` | Triggered when opening hours are changed                                     |

### store.opened

Triggered when a store is opened, when a snooze is ended early, or when a timed snooze expires automatically.

```json theme={null}
{
  "event": "store.opened",
  "data": {
    "venue": {
      "id": 1234,
      "name": "My Restaurant",
      "slug": "my-restaurant",
      "address": {
        "street1": "99-101 Regent St",
        "street2": "Victory House",
        "city": "London",
        "postCode": "W1B 4EZ",
        "companyName": "storekit",
        "coordinates": {
          "latitude": 51.5014,
          "longitude": 0.1419
        }
      }
    }
  }
}
```

### store.closed

Triggered when a store is closed or snoozed.

```json theme={null}
{
  "event": "store.closed",
  "data": {
    "closedReason": "Kitchen closing early",
    "closedUntil": "2024-01-15T18:00:00Z",
    "venue": {
      "id": 1234,
      "name": "My Restaurant",
      "slug": "my-restaurant",
      "address": {
        "street1": "99-101 Regent St",
        "street2": "Victory House",
        "city": "London",
        "postCode": "W1B 4EZ",
        "companyName": "storekit",
        "coordinates": {
          "latitude": 51.5014,
          "longitude": 0.1419
        }
      }
    }
  }
}
```

### store.opening\_hours.updated

Triggered when opening hours are changed for a store.

```json theme={null}
{
  "event": "store.opening_hours.updated",
  "data": {
    "venue": {
      "id": 1234,
      "name": "My Restaurant",
      "slug": "my-restaurant",
      "address": {
        "street1": "99-101 Regent St",
        "street2": "Victory House",
        "city": "London",
        "postCode": "W1B 4EZ",
        "companyName": "storekit",
        "coordinates": {
          "latitude": 51.5014,
          "longitude": 0.1419
        }
      }
    }
  }
}
```

***

## Item Events

Events related to menu item availability.

| Event               | Description                                  |
| ------------------- | -------------------------------------------- |
| `item.out_of_stock` | Triggered when a menu item goes out of stock |

### item.out\_of\_stock

Triggered when a menu item becomes unavailable. This can happen through several paths:

* **Manual snooze** — an admin snoozes the item from the dashboard
* **Manual disable** — an admin sets the item's availability to off
* **Inventory depletion** — the item's inventory reaches zero after an order
* **Integration sync** — a POS or integration (Deliverect, Lightspeed, Zonal) marks the item as unavailable

The `reason` field indicates why the item went out of stock, and `source` indicates what triggered it.

| Reason               | Description                  |
| -------------------- | ---------------------------- |
| `snoozed`            | Item was temporarily snoozed |
| `inventory_depleted` | Item inventory reached zero  |
| `disabled`           | Item was explicitly disabled |

| Source       | Description                                  |
| ------------ | -------------------------------------------- |
| `manual`     | Action taken by an admin in the dashboard    |
| `order`      | Inventory depleted by a customer order       |
| `deliverect` | Synced from Deliverect integration           |
| `lightspeed` | Synced from Lightspeed / iKentoo integration |
| `zonal`      | Synced from Zonal POS                        |
| `pos_sync`   | Synced from a generic POS availability push  |

```json theme={null}
{
  "event": "item.out_of_stock",
  "data": {
    "venue": {
      "id": 1234,
      "name": "My Restaurant"
    },
    "item": {
      "id": 5678,
      "name": "Margherita Pizza",
      "plu": "PLU-001",
      "posId": "pos_item_42",
      "sku": "SKU-MARG-001"
    },
    "reason": "snoozed",
    "source": "manual",
    "details": {
      "snoozeEnd": "2024-01-15T18:00:00Z"
    }
  }
}
```

The `details` object varies by reason:

* **`snoozed`** — includes `snoozeEnd` (ISO 8601 timestamp, or `null` for indefinite snoozes)
* **`inventory_depleted`** — empty `{}`
* **`disabled`** — empty `{}`

***

## Payments Events

Events related to payments and payouts.

| Event                           | Description                                                                            |
| ------------------------------- | -------------------------------------------------------------------------------------- |
| `payments.payout.created`       | Triggered when a payout is sent to your bank account                                   |
| `bill.payment.created`          | Triggered when a bill payment is created                                               |
| `payment_link.created`          | Triggered when a new payment link is created                                           |
| `payment_link.paid`             | Triggered when a payment is successfully collected via a payment link                  |
| `payment_link.refund.created`   | Triggered when a refund is initiated for a payment link payment                        |
| `payment_link.refund.succeeded` | Triggered when a payment link refund is confirmed as successful by the payment gateway |
| `payment_link.refund.failed`    | Triggered when a payment link refund is rejected by the payment gateway                |

### payments.payout.created

Triggered when storekit sends a payout to your bank account.

```json theme={null}
{
  "event": "payments.payout.created",
  "data": {
    "amounts": [
      {
        "currency": "GBP",
        "value": "3210.50"
      },
      {
        "currency": "GBP",
        "value": "1030.00"
      }
    ],
    "bankAccount": {
      "id": "db97e205-105c-42ff-8460-d06c25cb6830",
      "IBAN": "GB15HBUK40127612345678",
      "accountNumber": "0001234",
      "branchCode": "001234",
      "currency": "GBP"
    },
    "estimatedArrivalDate": "2024-01-17"
  }
}
```

### payment\_link.created

Triggered when a new payment link is created. Only fired for accounts with webhooks enabled.

```json theme={null}
{
  "event": "payment_link.created",
  "data": {
    "paymentLink": {
      "id": "plink_019dbc4d828174419d9ff9fae24aea7b",
      "title": "Invoice #001",
      "type": "one_off",
      "amountType": "fixed",
      "amount": 2500,
      "currency": "GBP",
      "reference": "INV-001"
    },
    "venue": {
      "id": 1234,
      "name": "My Restaurant",
      "slug": "my-restaurant"
    }
  }
}
```

| Field                    | Description                                                        |
| ------------------------ | ------------------------------------------------------------------ |
| `paymentLink.id`         | The payment link ID in `plink_` format                             |
| `paymentLink.type`       | `one_off` or `reusable`                                            |
| `paymentLink.amountType` | `fixed` or `variable`                                              |
| `paymentLink.amount`     | Fixed amount in minor currency units, or `null` for variable links |
| `paymentLink.currency`   | ISO 4217 currency code                                             |
| `paymentLink.reference`  | Your internal reference, if set                                    |
| `venue.slug`             | The venue's URL slug                                               |

### payment\_link.paid

Triggered when a payment is successfully collected via a payment link. Only fired for accounts with webhooks enabled.

```json theme={null}
{
  "event": "payment_link.paid",
  "data": {
    "paymentLink": {
      "id": "plink_019dbc4d828174419d9ff9fae24aea7b",
      "title": "Invoice #001",
      "type": "one_off",
      "amountType": "fixed",
      "reference": "INV-001"
    },
    "payment": {
      "transactionId": "txn_abc123",
      "amount": 2500,
      "currency": "GBP",
      "pspReference": "ABCD1234EFGH5678"
    },
    "venue": {
      "id": 1234,
      "name": "My Restaurant",
      "slug": "my-restaurant"
    }
  }
}
```

| Field                    | Description                                           |
| ------------------------ | ----------------------------------------------------- |
| `paymentLink.id`         | The payment link ID in `plink_` format                |
| `paymentLink.type`       | `one_off` or `reusable`                               |
| `paymentLink.amountType` | `fixed` or `variable`                                 |
| `paymentLink.reference`  | Your internal reference, if set                       |
| `payment.amount`         | Amount collected in minor currency units (e.g. pence) |
| `payment.pspReference`   | Adyen payment reference                               |
| `venue.slug`             | The venue's URL slug                                  |

### payment\_link.refund.created

Triggered when a refund is initiated for a payment link payment. The refund is pending at this point — confirmation arrives via `payment_link.refund.succeeded` or `payment_link.refund.failed` once the payment gateway processes it asynchronously.

```json theme={null}
{
  "event": "payment_link.refund.created",
  "data": {
    "paymentLink": {
      "id": "plink_019dbc4d828174419d9ff9fae24aea7b",
      "title": "Invoice #001",
      "reference": "INV-001"
    },
    "refund": {
      "id": "ref_xyz789",
      "transactionId": "txn_abc123",
      "amount": 1000,
      "currency": "GBP",
      "reason": "Item damaged"
    },
    "venue": {
      "id": 1234,
      "name": "My Restaurant",
      "slug": "my-restaurant"
    }
  }
}
```

| Field                  | Description                                        |
| ---------------------- | -------------------------------------------------- |
| `refund.id`            | The refund ID                                      |
| `refund.transactionId` | The transaction ID of the original payment         |
| `refund.amount`        | Refund amount in minor currency units (e.g. pence) |
| `refund.currency`      | ISO 4217 currency code                             |
| `refund.reason`        | Reason for the refund, if provided                 |

### payment\_link.refund.succeeded

Triggered when the payment gateway confirms a refund has been successfully processed. This fires asynchronously after `payment_link.refund.created`.

```json theme={null}
{
  "event": "payment_link.refund.succeeded",
  "data": {
    "paymentLink": {
      "id": "plink_019dbc4d828174419d9ff9fae24aea7b",
      "title": "Invoice #001",
      "reference": "INV-001"
    },
    "refund": {
      "id": "ref_xyz789",
      "transactionId": "txn_abc123",
      "amount": 1000,
      "currency": "GBP",
      "reason": "Item damaged"
    },
    "venue": {
      "id": 1234,
      "name": "My Restaurant",
      "slug": "my-restaurant"
    }
  }
}
```

### payment\_link.refund.failed

Triggered when the payment gateway rejects a refund. This fires asynchronously after `payment_link.refund.created`.

```json theme={null}
{
  "event": "payment_link.refund.failed",
  "data": {
    "paymentLink": {
      "id": "plink_019dbc4d828174419d9ff9fae24aea7b",
      "title": "Invoice #001",
      "reference": "INV-001"
    },
    "refund": {
      "id": "ref_xyz789",
      "transactionId": "txn_abc123",
      "amount": 1000,
      "currency": "GBP",
      "reason": "Item damaged"
    },
    "venue": {
      "id": 1234,
      "name": "My Restaurant",
      "slug": "my-restaurant"
    }
  }
}
```

***

## Printer Events

Events related to cloud printer status.

| Event                    | Description                                |
| ------------------------ | ------------------------------------------ |
| `printer.status.offline` | Triggered when a printer goes offline      |
| `printer.status.online`  | Triggered when a printer comes back online |

### printer.status.offline

Triggered when a connected cloud printer fails to check in to the storekit server for 5 minutes. An email notification is also sent to the venue's configured email address.

```json theme={null}
{
  "event": "printer.status.offline",
  "data": {
    "id": "6041b7c2-d402-4ff1-9adf-2863c65b61b1",
    "mac": "00-B0-D0-63-C2-26",
    "model": "StarMCPrint3",
    "name": "Kitchen Printer",
    "status": "offline"
  }
}
```

### printer.status.online

Triggered when a cloud printer reconnects to our servers after being offline for at least 5 minutes. An email notification is also sent to confirm the printer is back online.

```json theme={null}
{
  "event": "printer.status.online",
  "data": {
    "id": "6041b7c2-d402-4ff1-9adf-2863c65b61b1",
    "mac": "00-B0-D0-63-C2-26",
    "model": "StarMCPrint3",
    "name": "Kitchen Printer",
    "status": "online"
  }
}
```