Getting Ready for Age Verification: Testing the Amazon Appstore GetUserAgeData API
Audience: App developers and QA teams integrating the Amazon Appstore’s GetUserAgeData API ahead of app submission.
Purpose: A practical, self-contained guide for exercising the age-verification integration during your development and QA cycle — before you submit your app to the Amazon Appstore.
This guide is safe to share externally. It references only public Amazon developer documentation:
1. Background — what this is and why it matters
Several US states have passed App Store Accountability Acts (ASAA) that require app stores to verify users’ ages, obtain parental consent for users under 18, and share age signals with developers. Developers are, in turn, required to consume those signals and deliver age-appropriate experiences.
Current status of the major state laws (verify against the latest Amazon documentation, as dates change):
-
Texas (SB 2420) — in effect.
-
Utah ASAA — delayed to May 6, 2027.
-
Louisiana ASAA — delayed to July 1, 2027.
Amazon provides the GetUserAgeData API so your app can retrieve, for eligible users in applicable jurisdictions:
-
An age signal in one of four ranges: 0–12, 13–15, 16–17, or 18+.
-
For users under 18, the parental consent status for the current version of your app.
Your app is responsible for acting on these signals (age-gating content, gating on consent, etc.).
Note on payment methods: If your app uses payment methods outside of Amazon’s In-App Purchasing (IAP) APIs, you are responsible for implementing your own mechanisms to obtain parental consent for in-app purchases and to comply with all applicable laws.
2. How the API works
Your app queries the API through Android’s standard ContentProvider interface.
Production query URI: content://amzn_appstore/getUserAgeData
The response is returned as a row (JSON-equivalent fields) with:
| Field | Meaning |
|---|---|
responseStatus |
SUCCESS, APP_NOT_OWNED, INTERNAL_TRANSIENT_ERROR, INTERNAL_ERROR, or FEATURE_NOT_SUPPORTED. If not SUCCESS, all other fields are null/empty. |
userStatus |
VERIFIED (18+), SUPERVISED (under 18 with consent), UNKNOWN (age/consent not ascertainable), CONSENT_NOT_GRANTED (revoked / pending / denied re-consent), or "" (law not applicable, or app is part of Amazon Kids+). |
ageLower |
Lower bound of the range: 0, 13, 16, or 18. Null if UNKNOWN or empty. |
ageUpper |
Upper bound: 12, 15, 17, or null (18+). Null if VERIFIED, UNKNOWN, or empty. |
userId |
Anonymous, app-level identifier for the signed-in profile (under-18 users). Matches the ID used in consent-revocation reports. Null if VERIFIED, UNKNOWN, or empty. |
mostRecentApprovalDate |
ISO 8601 date of the most recent approved significant change. Null if VERIFIED, UNKNOWN, or empty. |
3. Important: what you can and cannot test today
You can test: your app’s integration logic and response handling, using Amazon’s provided mock (TestContentProvider) with predefined responses.
What you can test end-to-end today:the GetUserAgeData API is now returning live responses for eligible users in Texas (SB 2420 is in effect). For states whose laws have not yet taken effect, or if the feature is not yet enabled for your app, a production call may still return null, an Exception, or FEATURE_NOT_SUPPORTED. So, continue using the mock to exercise every response branch.
The significant-change (re-consent) workflow and consent-revocation reports are available in the Developer Console. To report a significant change follow the details onthis page during the app update flow. Follow the instruction onthis pageto download the Parental Consent Revocation Report.
Practical takeaway: Build and fully validate your integration now using the mock. Keep the production code path ready; the live API is already returning responses for eligible users in Texas, so switch to production values to validate there.
4. Setting up the mock test harness
Amazon ships a TestContentProvider class (see the Integrate and Test doc for the full source) that returns predefined responses. It’s completely standalone and does not contact Amazon systems — use it for development and QA only, never in production builds.
Step 1 — Point your client at the test endpoint
In your AmazonUserDataClient (or equivalent), use the test values:
| Setting | Test Value | Production value |
|---|---|---|
| AUTHORITY | amzn_test_appstore | amzn_appstore |
| PATH | /getUserAgeData?testOption=k (k = 1–11) | /getUserAgeData |
Step 2 — Register the TestContentProvider in your test app’s manifest
Only the app serving the mock needs this. Do not include it in your production build.
<application
android:name="{.MainApplication or your application}"
android:label="Test App">
<!-- Test content provider (test/QA builds only) -->
<provider
android:name="com.test_app.TestContentProvider"
android:authorities="amzn_test_appstore"
android:exported="true" />
</application>
Step 3 — Drive scenarios with the testOption parameter
Change testOption (1–11) to make the mock return each response combination.
5. Test matrix — the 11 mock scenarios
Run each of these and confirm your app behaves correctly. These map directly to the testOption values served by the mock.
Each testOption maps to a distinct response combination. Run all of them and confirm your app does the right thing:
| # | Scenario | responseStatus | userStatus | Age range | Example app behavior |
|---|---|---|---|---|---|
| 1 | 18+, verified | SUCCESS | VERIFIED | 18 / null | Full adult experience |
| 2 | Age/consent not ascertainable | SUCCESS | UNKNOWN | null | Safe default experience |
| 3 | Child 0–12 | SUCCESS | SUPERVISED | 0–12 | Youngest age-appropriate experience |
| 4 | Teen 13–15 | SUCCESS | SUPERVISED | 13–15 | Age-appropriate experience |
| 5 | Teen 16–17 | SUCCESS | SUPERVISED | 16–17 | Age-appropriate experience |
| 6 | Under 18, consent not granted / pending / revoked | SUCCESS | CONSENT_NOT_GRANTED | 0–12 (example) | Restrict or block per your policy |
| 7 | Law not applicable | SUCCESS | "" (empty) |
null | Standard experience |
| 8 | App not installed from Amazon Appstore | APP_NOT_OWNED | "" |
null | Graceful fallback; don’t crash |
| 9 | Transient error | INTERNAL_TRANSIENT_ERROR | "" |
null | Retry (max ~2), then degrade gracefully |
| 10 | Non-transient error | INTERNAL_ERROR | "" |
null | Don’t retry; degrade gracefully |
| 11 | Feature not enabled for this app | FEATURE_NOT_SUPPORTED | "" |
null | Graceful fallback |
Scenario 6 defaults to the 0–12 range, but you can adapt it to any valid band (0–12, 13–15, 16–17) to cover all of your consent-handling paths.
6. Dev & QA checklist (pre-submission)
Integration
-
[ ] App queries GetUserAgeData via ContentProvider and parses all six response fields.
-
[ ] A single, well-defined code path handles the response, with a short timeout (the sample uses ~5 seconds) so a slow/blocked query never hangs the UI.
-
[ ] Production AUTHORITY/PATH values are wired for release builds; test values only in test/QA builds.
-
[ ] TestContentProvider and its manifest entry are excluded from production builds.
Functional (run all 11 mock scenarios)
-
[ ] 18+ (VERIFIED) → full adult experience.
-
[ ] SUPERVISED 0–12, 13–15, 16–17 → correct age-appropriate experience for each band.
-
[ ] CONSENT_NOT_GRANTED → access is restricted/blocked per your policy.
-
[ ] UNKNOWN and empty (“”) → sensible safe defaults.
-
[ ] APP_NOT_OWNED, INTERNAL_ERROR, FEATURE_NOT_SUPPORTED → graceful fallback, no crash.
-
[ ] INTERNAL_TRANSIENT_ERROR → bounded retry (≤2), then graceful fallback.
Resilience
-
[ ] Null fields and unexpected/malformed responses are handled without crashing.
-
[ ] Query exceptions are caught and logged; the app remains usable.
-
[ ] Age-gating logic fails safe (defaults to the more restrictive experience) when the signal is missing or ambiguous.
Compliance readiness
-
[ ] You have a plan to report significant changes (which trigger renewed parental consent) via the Developer Console during app updates. Note: if you update via the App Submission API, significant changes must still be reported through the Developer Console.
-
[ ] You have a plan to consume consent-revocation reports (matched by the anonymous userId) which you can download now from the reporting section of the Developer Console (Refer to thislinkfor details).
-
[ ] If you use non-Amazon payment methods, you have your own parental-consent mechanism for in-app purchases.
Cutover
-
[ ] Production build switched to amzn_appstore / /getUserAgeData.
-
[ ] A monitoring/retry plan is in place for the live API (already enabled for eligible Texas users), with coverage expanding as more states take effect.
7. Other frameworks
The API is accessed the same way regardless of framework — it’s an Android ContentProvider query:
React Native
const userData = await
ContentResolver.query('content://amzn_appstore/getUserAgeData');
Flutter
final userData = await platform.invokeMethod('queryContentProvider', {
'uri': 'content://amzn_appstore/getUserAgeData'
});
(Example only — refer to your framework’s official documentation for complete syntax.)
8. Key reminders
-
Test with the mock now; The live production API is returning real responses for eligible users in Texas, so also validate against production there.
-
Age-gate on the four ranges (0–12 / 13–15 / 16–17 / 18+) and gate on consent for under-18 users.
-
Fail safe — when in doubt (UNKNOWN, errors, nulls), default to the more restrictive experience.
-
You remain responsible for your app’s compliance with all applicable laws and Amazon Appstore policies; the API is a tool to help, not a guarantee of compliance.
-
Watch the docs for date/behavior changes — the law effective dates and the API’s live status are evolving.
Sources (public): User Age Verification and Integrate and Test the GetUserAgeData API,last updated Jul 17, 2026 and Jul 16, 2026, respectively. Content was rephrased for compliance with licensing restrictions. Verify current law effective dates and API availability against the live documentation before relying on this guide.