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 and become available in the Dev Dashboard. 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 and are then validated and added as a charge to a merchant's invoice.

Anchor to Why use app eventsWhy use app events

App events give you a centralized view in the Dev Dashboard 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.
• 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.

Anchor to Types of eventsTypes of events

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

Anchor to Billing eventsBilling events

Billing events are tied to your usage-based subscriptions. 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.

Anchor to Custom eventsCustom 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.

Anchor to How it worksHow 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):

   Copy

   9

   1

   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 in the app submission form before Shopify can process billing events.

Anchor to PrerequisitesPrerequisites

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)

Anchor to AuthenticationAuthentication

All App Events API requests require a valid bearer token.

API keys created in the Dev Dashboard provide a client ID and secret that can be used to generate a JWT token.

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.

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 to investigate more details related to how Shopify issues this token. Request a new token before the current one expires.

Anchor to Required fieldsRequired fields

Anchor to View events in the Dev DashboardView events in the Dev Dashboard

After sending events, you can view and analyze them in the Dev Dashboard. Events are retained for 30 days.

1. Open the Dev Dashboard and click the app you want to monitor.
2. Navigate to Logs for detailed event records, or Monitoring for aggregated performance metrics.

Anchor to Filter events in logsFilter 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.

Anchor to Billing errorsBilling errors

Anchor to Troubleshooting with eventsTroubleshooting 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.

Anchor to Best practicesBest 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.

Anchor to Rate limitsRate 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.

Anchor to Error handlingError handling

Common error responses from the App Events API:

For a complete list, refer to the API status response and error codes.

Anchor to TermsTerms

By using the App Events API, you agree to the App Events API Terms of Service. Don't submit personal information such as names, email addresses, or any data that identifies a natural person.

Anchor to Next stepsNext steps

• Using App Events for a step-by-step tutorial.
• Build a billing event to power usage-based pricing.
• Create usage-based subscriptions to charge merchants based on billing events.
• Review the App Events API reference for the complete API specification.