Responses, filters and examples

These docs describe the source-defined API; example values and responses are illustrative. All sample requests and responses are synthetic and unexecuted. ${...} values are placeholders; example.com hosts and invented IDs are not production configuration. JSON examples labeled excerpts intentionally omit other fields.

Sample runtimes

JavaScript examples with top-level await use Node.js ES modules. Save them with a .mjs extension so Node treats them as modules.

Examples use cURL, Node.js 18+ with built-in fetch, and Python 3 with the standard-library urllib client. No Wallkit SDK or third-party Python library is assumed. Supply existing WALLKIT_API_BASE (scheme/host only), RESOURCE_KEY and, for member requests, USER_TOKEN through your environment. Add the Firebase ID-token header only for the configured member context. Query values and variable path segments must be encoded; examples use fixed safe synthetic path segments. Python catches HTTPError to show API error JSON; JavaScript prints HTTP status separately from the body. A network failure can occur before any API response and is not an allow/deny result.

Read the operation’s shape

Successful catalog/access reads normally return HTTP 200 JSON. Identity/profile operations also use branch-specific 201 and other outcomes: read their status separately from the business result. Lists commonly use items and paginator; detail and settings operations place their fields at the top level. Resource summaries instead contain items: [{"resources": [...]}]. The template response has its own top-level JSON and error shape. There is no shared data or success wrapper for every response.

Identity responses can merge user/session/auth fields in different orders; the operation identifies whether id is a user or session ID. Profile data uses a dynamic group map or flat items array; grouped DELETE has an ordinary empty JSON response. Refresh cleanup wraps acknowledgement in msg. The unavailable history-write route defines no reachable successful response. See identity, profile and extra-data definitions for the exact fields returned.

Operations that return a paginator object use the page fields below. The grouped account reads place resources inside a single items wrapper; page/limit count resources, not subscriptions, purchases or transactions within them. Use page=1 explicitly. Empty results are documented beside each call.

Field	Type	Meaning
`items`	array or operation-defined map	Result records, grouped-resource wrapper, or grouped extra-data map; follow the operation.
`paginator.current_page`	integer	Current result page.
`paginator.page`	integer	Same current page, retained as an additional field.
`paginator.total_pages`	integer	Number of pages for this selection.
`paginator.total_items`	integer	Count of selected records; resources for grouped reads.
`paginator.limit`	integer	Requested/configured outer page size. No universal maximum is defined here.

The integration attendee list instead returns items, total, limit, offset and has_more. Its total counts distinct users while rows group users by ticket, so has_more can understate remaining rows. It has no paginator object; follow its own limit/offset and empty-result rules.

Where a page permits Criteria-style filter, use bracket query notation such as filter[Plans.id]=1001 or a JSON-encoded object. Model-qualified fields avoid ambiguity. Text matching is case-insensitive substring matching; numeric array/comma-separated inputs select membership, and booleans select true/false. Unknown fields do not define new filters. The resource-list and team-plan operations use their own bracket-object filters; their pages identify the difference. Avoid relying on unlisted database fields or a universal sorting contract.

Errors and access decisions

Ordinary errors contain error, error_description and req_guid; additional fields can be present. Example HTTP 404:

{"error":"resource_not_exists","error_description":"Incorrect resource key","req_guid":"example-request"}

HTTP status	API code	Cause	Next action
401	auth_failed	Required identity missing.	Supply the existing member token or the permitted stable guest session.
401	auth_access_fail	Inactive account or locked/suspended resource relationship.	Ask the administrator to check activation and relationship restrictions.
401	token_expired / token_compromised	Enforced session check rejects the token.	Use your integration’s existing session/sign-in flow for a current token.
401	firebase_token_compromised	Applicable Firebase verification fails.	Supply the configured current Firebase ID token alongside the Wallkit token.
401 / 403	access	Role/action permission missing.	Use the required permitted identity; 403 applies to established non-guest context.
404	resource_not_exists	Resource key fails to resolve.	Check the public resource key and selected integration context.
409	initialize_failed	Context initialization fails.	Check integration configuration with the administrator; provide req_guid to support.

Error field	Type	Meaning
`error`	string	API code identifying the failure.
`error_description`	string / null	Explanation; exception-only error paths can leave it null. Use the code and condition for recovery.
`req_guid`	string	Request reference for support; some direct integration error shapes omit it.

Embedded integration operations and current-resource configuration omit the ordinary token expiry/revocation check, but still enforce role and operation context. Operation-specific errors are listed with each call. A 409 may describe initialization, validation or synchronization failure; it does not always mean a duplicate/conflict.

An access check can successfully return HTTP 200 with allow: false. Treat that as an access decision and use reason/message; do not interpret 200 as permission. GET access checks can record allowed views and activity; sync-and-check can create records. Repeated requests can therefore have side effects. Do not treat rnd as an idempotency guarantee; examples omit it.

Optional response diagnostics

Responses using the ordinary response flow may add these fields when server debugging applies. They are not required business fields and do not change allow/deny or collection interpretation.

Field	Type / presence	Meaning
`executed_time`	number; optional	Server elapsed time in seconds, rounded to four decimals, when a start time is available.
`memory_peak`	string; optional	Server peak memory value using an .mb suffix.
`server`	string; optional	Server operating-system/PHP version description.
`req_guid`	string; optional on success	Request reference. Access decisions and ordinary errors define it separately.

Monetary units, timestamp timezone and unlisted business enums remain unspecified unless the exact object definition establishes them. Do not infer cents, UTC or a closed enum from illustrative values.

Checkout records and binary documents

Checkout uses JSON item arrays for member calculation/payment and different JSON objects for provider/single-Pricing branches. Calculation items are not saved purchases. Transaction status and HTTP success need operation-specific interpretation; a 406 payment can retain processed transactions and a 200 can require further authentication. Account purchase fields distinguish base, list and detail projections, including the purchase-list sub_total anomaly.

Invoice and receipt downloads stream bytes. Check HTTP status and media type; parse JSON only when a JSON error/result is actually returned. The invoice generator sets application/force-download; receipt download forwards private-storage ContentType, and the documented receipt uploader stores pdf as that value. No standard application/pdf label or JSON success wrapper is universal here.

Receipt-generation success:true acknowledges an event request, not document availability/delivery. A successful stored receipt download updates a counter. Neither a PDF nor a purchase record replaces the content decision.

Before repeating a request

Choose recovery from the operation’s effect and current state, not its HTTP method alone. Access GETs can record views; provider-preference GETs can synchronize contacts or audience state; service GETs can update sessions and audit records. Event acknowledgements do not prove delivery, and an error can follow a local/provider write.

There is no shared idempotency, retry delay, rate-limit window or transaction guarantee across these operations. Correct invalid input/context first. For an uncertain mutation or provider result, inspect the documented state with the integration owner before another write. The Server-integrations (advanced) shows existing-record versus absent-record handling; 3rd party integration flows preserves provider-specific partial results. Do not interpret HTTP 200, success:true or an empty list beyond the selected contract.