Service eligibility and regional restrictions
PuppyIP serves only compliant overseas businesses and their authorized personnel. Proxy services are not available in mainland China. The service may only be used for lawful business activities outside mainland China. Use of this service within mainland China is prohibited.
Hosting a proxy IP or server overseas does not change these restrictions. The service must not be provided to end users in mainland China through relaying, forwarding, sharing or resale. Before use, read the Terms of Service.
Key Takeaways
- Admin UI extensions require API 2027-01 or later. Embedded App Home uses App Bridge.
- Should-render and data targets cannot send events.
- Both surfaces allow a burst of 20 followed by 2 events per second. The limits apply at different scopes.
- Use UI events to observe app usage. Report Shopify App Pricing usage with backend billing events.
Identify the surface that sent the event
For an Admin UI extension, check that api_version in shopify.extension.toml is 2027-01 or later. Earlier versions do not expose shopify.appEvents. Even on a supported version, should-render and data targets do not send events. Calls on those targets return success: false with Emit is unavailable.
Embedded App Home must load App Bridge. Shopify did not specify an API version for this surface. The Promise can remain pending while App Bridge waits for the admin handshake. Keep event reporting separate from saves, navigation, and other steps the merchant must wait for.
Verify the emit result and the Shopify log separately
Use a development store with shopify app dev to complete the actual UI action. Record the test time, shop, and event handle. If emit returns success: false, read error and check for an unsupported target, invalid attributes, or rate limits. If it returns success: true, open Dev Dashboard → Logs and narrow the results by App Event, time, and shop.
If the admin accepted it but Logs show nothing, Shopify may not have received the event or may have dropped it during later validation. Check the app installation, session validity, handle, and attributes. A custom handle can be report_exported. Use the corresponding shopify. handle only for a declared event that matches the official standard event definition.
Check bursts and event attributes
Each Admin UI extension allows a burst of up to 20 events, followed by 2 per second. For embedded App Home, an app has the same budget within a single Shopify admin tab. Its pages, modals, and app intents share that budget. Repeated rendering or double clicks can emit multiple events, so emit once for each action you actually want to count.
For a report export event, use nonpersonal attributes such as format and row count. Attributes can contain up to 15 keys. Keys are limited to 64 characters, and string values to 128 UTF-8 characters. Use strings, numbers, or booleans, and omit arrays, nested objects, and personal identifiers such as names, email addresses, staff IDs, and customer IDs.
Verify usage logs and billing separately
When a merchant exports a report, you can send report_exported to observe use of the feature. Shopify App Pricing does not process admin UI events for billing. If you need to report billable usage, send a billing event from your backend under Shopify's billing rules.
Keep a development-store verification record with the surface, extension API version or App Bridge, handle, return value, and whether Logs showed the event. If the app needs to verify a charge, check the processing status of the backend billing event separately.
Sources
Frequently Asked Questions
Does success: true prove delivery?
It means Shopify admin accepted the send request. To verify delivery, look in Dev Dashboard Logs for the shop and time range.
Does App Home also require 2027-01?
The 2027-01 or later requirement applies to Admin UI extensions. Embedded App Home uses App Bridge, and Shopify's announcement does not apply that version requirement to it.
Why shouldn't a form save wait for emit?
An App Home call can still be waiting for its App Bridge handshake. Keeping usage reporting outside the merchant's completion path avoids delaying saving or navigation.