# Events

Source: https://developers.swell.is/backend-api/events

The Events model is a running history of all events that occur within your store. Swell is built on an event-based architecture that lets you configure functions and webhooks for any events that occur within both standard and custom data models. Standard models are configured with many built-in [event types](https://developers.swell.is/backend-api/events/event-types), and also may be installed automatically by Swell Apps.

> **Tip:** See the [Apps event reference](https://developers.swell.is/apps/events) to learn how to configure custom events with Swell Apps.

## The event model

### Fields

- `id` (objectId): The unique identifier for the event.
- `date_created` (date, auto): Date and time the event was created.
- `date_updated` (date, auto): Date and time the event was updated.
- `app_id` (objectId): ID of the app that generated the event, if applicable.
- `model` (string, required): The name of the model for which the events are associated.
- `type` (string, required): The trigger type for the event.
- `data` (object): The data or payload of the event.
  - `id` (objectId): The unique identifier for the event data object.
- `notes` (string): Notes stored on the event's webhook.
- `req_id` (objectId): ID of the request that triggered the event.
- `user_id` (objectId): ID of the user that configured the webhook which triggers the event.
- `webhooks_pending` (int): The number of webhooks still pending to fire.
- `webhooks` (array of Webhooks): An array of pending webhooks

### Example request

**The event model**

### Example response

```json
{
  "model": "accounts",
  "type": "account.created",
  "data": {
    "email": "martinseptim@waynonpriory.net",
    "first_name": "Martin",
    "last_name": "Septim",
    "password": "theblades123",
    "email_optin": true,
    "currency": "USD",
    "name": "Martin Septim",
    "date_created": "2022-06-27T03:39:45.152Z",
    "type": "individual",
    "order_count": 0,
    "order_value": 0,
    "balance": 0,
    "id": "62b9268145139e0019e246ca"
  },
  "date_created": "2022-06-27T03:39:45.461Z",
  "date_updated": "2022-06-27T03:39:45.875Z",
  "webhooks_pending": 0,
  "id": "62b9268145139e0019e246cb"
}
```


## Retrieve an event

Retrieve an existing event using the id that was returned during creation.

### Arguments

- `id` (objectId, required): The unique identifier for the event.

### Example request

`GET events/{id}`

**Node**

```javascript
const { swell } = require('swell-node');
swell.init('store-id', 'secret-key');

await swell.get('/events/{id}', {
  id: '62bc64bc2fafef0019eb2325'
});
```

**PHP**

```php
<?php $swell = new \Swell\Client('store-id', 'secret-key');

$swell->get('/events/{id}', [
  'id' => '62bc64bc2fafef0019eb2325'
]);
```

**cURL**

```sh
$ curl https://api.swell.store/events/62bc64bc2fafef0019eb2325 \
  -u store-id:secret-key
```

### Example response

```json
{
  "user_id": "606f0fdd255b020caaa3f577",
  "model": "shipments",
  "type": "shipment.created",
  "data": {
    "order_id": "62bc642d912a9800199ea465",
    "items": [
      {
        "product_id": "628ba3c7499bba0019b1a961",
        "order_item_id": "62bc63892fafef0019eb2312",
        "quantity": 1,
        "id": "62bc64bc2fafef0019eb231f"
      },
      {
        "product_id": "628ba442499bba0019b1a96d",
        "order_item_id": "62bc639293cb7c0019423b5f",
        "quantity": 1,
        "id": "62bc64bc2fafef0019eb2320"
      },
      {
        "product_id": "628ba6011869c10019b41f70",
        "order_item_id": "62bc639e629aa900197ff786",
        "quantity": 1,
        "id": "62bc64bc2fafef0019eb2321"
      },
      {
        "product_id": "628ba67a1869c10019b41f76",
        "order_item_id": "62bc63a293cb7c0019423b63",
        "quantity": 1,
        "id": "62bc64bc2fafef0019eb2322"
      },
      {
        "product_id": "628ba6b7499bba0019b1a9b2",
        "order_item_id": "62bc63a793cb7c0019423b66",
        "quantity": 1,
        "id": "62bc64bc2fafef0019eb2323"
      },
      {
        "product_id": "628ba701499bba0019b1a9bb",
        "order_item_id": "62bc63aa93cb7c0019423b69",
        "quantity": 1,
        "id": "62bc64bc2fafef0019eb2324"
      }
    ],
    "service": "international",
    "tracking_code": null,
    "carrier": null,
    "notes": "Let's hope the packages get past the Gatekeeper...",
    "service_name": "International",
    "destination": {
      "name": "Sheogorath",
      "address1": "New Sheoth Palace",
      "address2": null,
      "city": "Shivering Isles",
      "state": "TX",
      "zip": "78757",
      "country": "US",
      "phone": null
    },
    "date_created": "2022-06-29T14:42:04.017Z",
    "number": "S100004",
    "id": "62bc64bc2fafef0019eb231e"
  },
  "date_created": "2022-06-29T14:42:04.272Z",
  "id": "62bc64bc2fafef0019eb2325"
}
```


## List all events

Return a list of events.

### Arguments

- `expand` (string): Expand link fields and child collections by using the expand argument.

  - For example, `expand=account` would return a related customer account if one exists.

  When the field represents a collection, you can specify the query limit.

  - For example, `expand=variants:10` would return up to 10 records of the variants collection.

  See [expanding](https://developers.swell.is/backend-api/querying/expanding) for more details.
- `fields` (string): Returns only the specified fields in the result.

  - For example `fields=name,slug` would return only the fields `name` and `slug` in the response.

  Supports nested object and array fields using dot-notation.

  - For example, `items.product_id`. The product `id` is always returned.
- `include` (object): Include one or more arbitrary queries in the response which are potentially related to the main query.

  See [including](https://developers.swell.is/backend-api/querying/including) for more details.
- `limit` (int): Limit the number of records returned, ranging between `1` and `1000`. Defaults to `15`. Default: `15`.
- `page` (int): The page number of results to return given the specified or default `limit`.
- `search` (string): A text search is performed using the search argument. Searchable fields are defined by the model.

  - For example, `search=red` would return records containing the word "red" anywhere in the defined text fields.

  See [searching](https://developers.swell.is/backend-api/querying/searching) for more details.
- `sort` (string): Expression to sort results by using a format similar to a SQL sort statement.

  - For example, `sort=name asc` would return records sorted by name ascending.

  See [sorting](https://developers.swell.is/backend-api/querying/sorting) for more details.
- `where` (object): An object with criteria to filter the result.

  - For example, `active=true` would return records containing a field `active` with the value `true`.

  It's also possible to use query operators, for example, `$eq`, `$ne`, `$gt`, and more.

  See [querying](https://developers.swell.is/backend-api/querying) for more details.

### Example request

`GET /events`

**cURL**

```sh
$ curl https://api.swell.store/events \
  -u store-id:secret-key
```

**Node**

```javascript
const { swell } = require('swell-node');
swell.init('store-id', 'secret-key');

await swell.get('/events');
```

**PHP**

```php
<?php $swell = new \Swell\Client('store-id', 'secret-key');

$swell->get('/events');
```

### Example response

```json
{
  "count": 1105,
  "results": [
    {
      "user_id": "606f0fdd255b020caaa3f577",
      "model": "accounts",
      "type": "account.updated",
      "data": {
        "id": "62b1e36767145000197b2bd6",
        "shipping": {
          "first_name": "Runs-in-circles",
          "last_name": null,
          "company": "",
          "address1": "Shivering isles",
          "address2": null,
          "city": null,
          "zip": "34534",
          "country": "US",
          "state": "AL",
          "phone": null,
          "name": "Runs-in-circles",
          "account_address_id": "62bcb8ec629aa900197ffb8d"
        }
      },
      "date_created": "2022-06-29T20:41:17.225Z",
      "id": "62bcb8ed629aa900197ffb8f"
    },
    {
      "user_id": "606f0fdd255b020caaa3f577",
      "model": "accounts:addresses",
      "type": "account.address.created",
      "data": {
        "parent_id": "62b1e36767145000197b2bd6",
        "name": "Runs-in-circles",
        "first_name": "Runs-in-circles",
        "last_name": null,
        "address1": "Shivering isles",
        "address2": null,
        "city": null,
        "state": "AL",
        "zip": "34534",
        "country": "US",
        "phone": null,
        "company": null,
        "fingerprint": "0f1d3af32dd2dc0607c12ace5b2ea9c5",
        "date_created": "2022-06-29T20:41:16.931Z",
        "active": true,
        "id": "62bcb8ec629aa900197ffb8d"
      },
      "date_created": "2022-06-29T20:41:17.192Z",
      "id": "62bcb8ed629aa900197ffb8e"
    },
    {
      "model": "settings",
      "type": "setting.updated",
      "data": {
        "id": "store",
        "settings": {
          "date_updated": "2022-06-29T19:45:22.163Z"
        }
      },
      "date_created": "2022-06-29T19:45:22.598Z",
      "id": "62bcabd2bc89e4001a4c4ecf"
    },
    {
      "user_id": "606f0fdd255b020caaa3f577",
      "model": "settings",
      "type": "setting.updated",
      "data": {
        "id": "store",
        "settings": {
          "date_updated": "2022-06-29T19:40:52.478Z"
        }
      },
      "date_created": "2022-06-29T19:40:53.402Z",
      "id": "62bcaac5629aa900197ffb35"
    },
    {...}
  ],
  "page": 1,
  "page_count": 74,
  "limit": 15,
  "pages": {
    "1": {
      "start": 1,
      "end": 15
    },
    "2": {
      "start": 16,
      "end": 30
    },
    "3": {
      "start": 31,
      "end": 45
    },
    "4": {
      "start": 46,
      "end": 60
    },
    "5": {
      "start": 61,
      "end": 75
    },
    "6": {
      "start": 76,
      "end": 90
    },
    "7": {
      "start": 91,
      "end": 105
    },
    "8": {
      "start": 106,
      "end": 120
    },
    "9": {
      "start": 121,
      "end": 135
    },
    "10": {
      "start": 136,
      "end": 150
    }
  }
}
```


## Event types

These are the event types that are currently recorded in Swell, grouped by model. They use a common naming convention and all models (including custom ones) have the basic events `.created`, `.updated`, and `.deleted`. Some models also trigger events specific to their functionality.

> **Tip:** You can see an example of a model payload below by selecting an event type.

- `account.account-card.created`: Occurs when a credit card is added to an account.
- `account.account-card.deleted`: Occurs when a credit card is deleted from an account.
- `account.account-card.updated`: Occurs when an account’s credit card information changes.
- `account.address.created`: Occurs when an address is added to an account.
- `account.address.deleted`: Occurs when an address is deleted from an account.
- `account.address.updated`: Occurs when an account’s address changes.
- `account.created`: Occurs when an account is created.
- `account.credit.created`: Occurs when store credit is added to an account. 
- `account.credit.deleted`: Occurs when an account’s store credit is deleted.
- `account.credit.updated`: Occurs when the details of an account’s store credit changes.
- `account.deleted`: Occurs when an account is deleted.
- `account.updated`: Occurs when an account’s information changes.
- `cart.abandoned`: Occurs when products in a cart are left and not paid for.
- `cart.converted`: Occurs when a cart is converted to an order.
- `cart.created`: Occurs when a product is added to a cart.
- `cart.deleted`: Occurs when a cart is deleted.
- `category.created`: Occurs when a category is created.
- `category.deleted`: Occurs when a category is deleted.
- `category.products.added`: Occurs when a product is added to a category.
- `category.products.removed`: Occurs when a product is removed from a category.
- `category.updated`: Occurs when the properties of a category change.
- `contact.created`: Occurs when an contact information is added to an account. 
- `contact.deleted`: Occurs when contact information is deleted from an account. 
- `contact.updated`: Occurs when an contact's information changes.
- `coupon.code.created`: Occurs when a coupon code is created.
- `coupon.code.deleted`: Occurs when a coupon code is deleted.
- `coupon.created`: Occurs when a coupon is created.
- `coupon.deleted`: Occurs when a coupon is deleted.
- `coupon.generation.completed`: Occurs when a series of coupon codes are generated. 
- `coupon.updated`: Occurs when the details of a coupon change.
- `invoice.created`: Occurs when an invoice is created.
- `invoice.deleted`: Occurs when an invoice is deleted.
- `invoice.refund_failed`: Occurs when an attempt to refund an invoice fails. 
- `invoice.refund_succeeded`: Occurs when an attempt to refund an invoice succeeds. 
- `invoice.updated`: Occurs when invoice details change.
- `order.canceled`: Occurs when an order is canceld
- `order.created`: Occurs when an order is created.
- `order.deleted`: Occurs when an order is deleted.
- `order.delivered`: Occurs when a shipment is marked delivered
- `order.paid`: Occurs when an order is paid.
- `order.submitted`: Occurs when an order is submitted.
- `order.updated`: Occurs when order details change.
- `page.created`: Occurs when a page is created.
- `page.deleted`: Occurs when a page is deleted.
- `page.updated`: Occurs when information on a page changes.
- `payment.failed`: Occurs when a payment attempt fails. 
- `payment.refund.failed`: Occurs when an attempt to refund payment fails. 
- `payment.refund.succeeded`: Occurs when an attempt to refund payment succeeds. 
- `payment.refund.voided`: Occurs when an attempt to refund payment is voided. 
- `payment.succeeded`: Occurs when a payment attempt succeeds. 
- `payment.voided`: Occurs when a payment is voided. 
- `products.created`: Occurs when a product is created.
- `products.deleted`: Occurs when a product is deleted.
- `products.stock_adjusted`: Occurs when product stock details change.
- `products.updated`: Occurs when the properties of a product change.
- `products.variant.created`: Occurs when a product variant is created.
- `products.variant.deleted`: Occurs when a product variant is deleted.
- `products.variant.updated`: Occurs when the properties of a product variant change.
- `promotion.created`: Occurs when a promotion is created.
- `promotion.deleted`: Occurs when a promotion is deleted.
- `promotion.updated`: Occurs when a promotion is updated.
- `settings.updated`: Occurs when the properties of your store setting change.
- `shipment.canceled`: Occurs when a shipment is canceled.
- `shipment.created`: Occurs when a shipment is created.
- `shipment.deleted`: Occurs when a shipment is deleted
- `shipment.updated`: Occurs when the shipment details change.
- `subscription.activated`: Occurs when a subscription is activated
- `subscription.canceled`: Occurs when a subscription is cancelled
- `subscription.created`: Occurs when a subscription plan is created.
- `subscription.deleted`: Occurs when a subscription is deleted
- `subscription.invoiced`: Occurs when a subscription plan is invoiced.
- `subscription.paid`: Occurs when a subscription plan is paid.
- `subscription.paused`: Occurs when a subsription is paused
- `subscription.resumed`: Occurs when a subscription plan is resumed.
- `subscription.trial_ended`: Occurs when a subscription's trial period ends
- `subscription.trial_ended`: Occurs when a subscription's trial period ends
- `subscription.trial_will_end`: Occurs when a subscriptions trial is near ending
- `subscription.updated`: Occurs when an account’s subscription plan changes.