---
title: About App Events
description: >-
  Send custom and billing events from your app to Shopify, and monitor them in
  the Dev Dashboard.
source_url:
  html: 'https://shopify.dev/docs/apps/build/app-events'
  md: 'https://shopify.dev/docs/apps/build/app-events.md'
---

# About App Events

App Events let you send information about what's happening in your app to Shopify. When something meaningful occurs in your app, like a merchant starting and completing onboarding, or an SMS is sent that could be billed for, you can send that event to Shopify through the App Events API.

All events are sent to the [App Events API](https://shopify.dev/docs/api/app-events) and become available in the [Dev Dashboard](https://shopify.dev/docs/apps/build/dev-dashboard/monitoring-and-logs). Every event is tied to a specific shop, giving you per-merchant visibility into how your app is being used. Billing events must first be configured in [usage-based billing](https://shopify.dev/docs/apps/launch/billing/shopify-app-pricing/subscription-billing/setup-usage-charges) and are then validated and added as a charge to a merchant's invoice.

***

## Why use app events

App events give you a centralized view in the [Dev Dashboard](https://shopify.dev/docs/apps/build/dev-dashboard/monitoring-and-logs) to help you understand your whole app business:

* **Centralized logging**: View all your app's events in one place alongside webhook and function logs in the [Dev Dashboard](https://shopify.dev/docs/apps/build/dev-dashboard/monitoring-and-logs).
* **Power usage-based pricing**: Report billing events that feed into Shopify App Pricing to calculate usage-based charges.
* **Send custom events**: See how merchants interact with your app, track errors and failures, and identify friction points to improve the quality and reliability of your app.

***

## Types of events

There are two types of events you can send to Shopify:

### Billing events

Billing events are tied to your [usage-based subscriptions](https://shopify.dev/docs/apps/launch/billing/shopify-app-pricing/subscription-billing/setup-usage-charges). Once you configure your pricing and send a billing event, Shopify uses it to calculate usage-based charges for the merchant. Examples include:

* **Messages sent**: SMS notifications, emails, or push notifications sent on behalf of a merchant.
* **Orders processed**: Orders recovered, fulfilled, or synced through your app.
* **AI generations**: AI tokens, image generations, or content created.
* **Premium features used**: Advanced reports generated, exports created, or premium tools accessed.

Learn more about [usage-based subscriptions](https://shopify.dev/docs/apps/launch/billing/shopify-app-pricing/subscription-billing/setup-usage-charges).

### Custom events

Custom events let you track anything else that's meaningful for your app. Use them to understand merchant behavior, monitor operational health, or debug issues. Here are some examples:

**Business events**

* A merchant completed your app's onboarding flow.
* A merchant activated or deactivated a feature.
* A merchant created, updated, or deleted a resource in your app (campaigns, rules, templates).
* A merchant completed a bulk operation or workflow.

**Operational events**

* A data sync failed for a merchant.
* A connection to a third-party service timed out.
* A background job completed or failed.
* Your app encountered a rate limit or API error.

**Other events**

* A merchant viewed a specific page or dashboard in your app.
* A merchant exported data or generated a report.
* A scheduled task ran for a merchant.

**Caution:**

Don't include any data that, alone or in combination with other data, could identify an individual. This includes any merchant or buyer information, such as name, email address, phone number, and other identifiable data points. Use anonymized identifiers and aggregated metrics instead.

***

## How it works

Sending app events follows a straightforward flow:

1. Your app sends one event per request to the App Events API endpoint (batch requests aren't supported):

   https://api.shopify.com/app/{API\_VERSION}/events

2. Shopify ingests and stores the events. Events are retained for 30 days.

3. Events appear in the Dev Dashboard under **Monitoring** and **Logs**, where you can filter, search, and analyze them.

4. For billing events, Shopify aggregates usage and calculates charges based on your pricing structure. You must first [set up usage-based pricing](https://shopify.dev/docs/apps/launch/billing/shopify-app-pricing/subscription-billing/setup-usage-charges) in the app submission form before Shopify can process billing events.

***

## Prerequisites

Before you start sending events, make sure you have the following:

* An authenticated Shopify app with a valid access token
* Your app's client ID (available in the Partner Dashboard under **Apps > Your App > Overview**)

***

## Authentication

All App Events API requests require a valid bearer token.

API keys created in the [Dev Dashboard](https://dev.shopify.com/dashboard/) provide a client ID and secret that can be used to generate a JWT token.

POST

## https://api.shopify.com/auth/access\_token

```bash
curl --request POST \
  --url https://api.shopify.com/auth/access_token \
  --header 'Content-Type: application/json' \
  --data '{
    "client_id": "{your_client_id}",
    "client_secret": "{your_client_secret}",
    "grant_type": "client_credentials"
  }'
```

The response will contain:

* `access_token`: A JWT access token that can be used to interact with the App Events API.
* `scope`: The list of access scopes that were granted to your API key.
* `expires_in`: The number of seconds until the access token expires.

## {} Response

```json
{
    "access_token": "f8563253df0bf277ec9ac6f649fc3f17",
    "scope": "write_global_api_app_events",
    "expires_in": 3599
}
```

Include your token as a `Authorization: Bearer {token}` header on all API requests. Access tokens expire after 60 minutes. You can use a JWT decoder tool like [`jwt.io`](https://www.jwt.io/) to investigate more details related to how Shopify issues this token. Request a new token before the current one expires.

***

## Required fields

| Field | Description |
| - | - |
| `shop_id` | The shop ID as a numeric string (`"23423423"`) or GID (`"gid://shopify/Shop/23423423"`). |
| `event_handle` | A descriptive name for the event type (for example, `onboarding_completed`, `feature_used`). The prefix `shopify.` is reserved and can't be used. For billing events, this must exactly match a meter handle from your pricing configuration. |
| `timestamp` | The ISO 8601 timestamp when the event occurred. |
| `idempotency_key` | A unique key to prevent duplicate events. Maximum 64 characters. The API enforces a 24-hour idempotency window. For billing events, idempotency is enforced permanently. |
| `attributes` | A required JSON object containing the event data. For billing events, must include a `value` field (greater than 0) specifying the quantity to add to the meter. For custom events, include any key/value pairs that help you analyze or troubleshoot. |

POST

## https://api.shopify.com/app/unstable/events

```bash
curl -X POST \
  'https://api.shopify.com/app/unstable/events' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {BEARER_TOKEN}' \
  -d '{
    "shop_id": "gid://shopify/Shop/23423423",
    "event_handle": "sms_sent",
    "timestamp": "2026-01-27T14:30:00Z",
    "idempotency_key": "evt_55667788",
    "attributes": {
      "value": 1
    }
  }'
```

***

## View events in the Dev Dashboard

After sending events, you can view and analyze them in the [Dev Dashboard](https://dev.shopify.com). Events are retained for 30 days.

1. Open the [Dev Dashboard](https://dev.shopify.com) and click the app you want to monitor.
2. Navigate to **Logs** for detailed event records, or **Monitoring** for aggregated performance metrics.

### Filter events in logs

In the Logs view, all events sent through the App Events API appear alongside your functions and webhooks. Use the **Type** filter to narrow down what you see:

* **App Event**: Shows all events sent to the App Events API, including both custom and billing events.
* **App Billing Event**: Shows only events that have been processed by Shopify App Pricing as usage-based billing events.

You can also filter by time range, status, and shop to investigate specific issues.

### Billing errors

**Info:**

The App Events API always returns a `202` response when it receives your request, even if the event fails billing validation. There's no synchronous billing error response and no webhooks for billing validation failures. The Dev Dashboard is the only place to see billing errors — go to **Logs** and filter by **App Billing Event** to check for failures.

### Troubleshooting with events

* **Investigate errors**: Filter by a merchant's shop domain, then look for events with error-related handles (for example, `http_error` or `job_failure`). Inspect the event metadata for details like status codes and error messages.
* **Monitor after deployments**: Set the time range to the last day and watch for increases in error rates or unusual changes in event volume.
* **Track feature adoption**: Filter by event types related to a specific feature to see adoption trends over time.

***

## Best practices

* **Be consistent with event types**: Use a naming convention for your `event_handle` values (for example, `snake_case`) so they're easy to filter and search in the Dev Dashboard.
* **Include accurate timestamps**: Always set `timestamp` to the time the event actually happened in your app, not the time you sent it to Shopify. This keeps your logs and monitoring data accurate even if events are batched or delayed.
* **Keep metadata structured**: Include relevant context in your event attributes so you can filter and troubleshoot effectively without needing to cross-reference other systems.
* **Separate behavioral and troubleshooting events**: Use distinct `event_handle` values for behavioral tracking versus error monitoring. This makes it easier to set up focused views in the dashboard.
* **Use unique idempotency keys**: Always include a unique `idempotency_key` to prevent duplicate events if you need to retry a request.
* **Test in development**: Use a development store to verify your events work correctly before going live.

***

## Rate limits

The App Events API has a rate limit of 500 requests per second per app. If you exceed this limit, requests are throttled and return a `429 Too Many Requests` response.

To stay within limits:

* Implement exponential backoff when you receive `429` responses.
* Queue events in your app and send them sequentially rather than all at once. Each request sends a single event — batch requests aren't supported.

***

## Error handling

Common error responses from the App Events API:

| Status code | Description |
| - | - |
| `202 Accepted` | The event was received successfully. |
| `401 Unauthorized` | Your access token is missing or invalid. |
| `429 Too Many Requests` | You've exceeded the rate limit. Retry with exponential backoff. |
| `5xx` | An internal Shopify error. Check the [Shopify status page](https://www.shopifystatus.com) for more information. |

For a complete list, refer to the [API status response and error codes](https://shopify.dev/api/usage/response-codes).

***

## Terms

By using the App Events API, you agree to the [App Events API Terms of Service](https://shopify.com/legal/app-events-terms). Don't submit personal information such as names, email addresses, or any data that identifies a natural person.

***

## Next steps

* [Using App Events](https://shopify.dev/docs/apps/build/app-events/send-events) for a step-by-step tutorial.
* [Build a billing event](https://shopify.dev/docs/apps/launch/billing/shopify-app-pricing/subscription-billing/build-billing-event) to power usage-based pricing.
* [Create usage-based subscriptions](https://shopify.dev/docs/apps/launch/billing/shopify-app-pricing/subscription-billing/setup-usage-charges) to charge merchants based on billing events.
* Review the [App Events API reference](https://shopify.dev/docs/api/app-events) for the complete API specification.

***