Getting started

Start with the job your integration needs to do. Wallkit can identify members, show catalog choices, manage local account records and decide whether a visitor may access content. Payment providers, email integrations, teams, passes and sponsorships have their own workflows and credentials.

Understand the five core terms

Term	Meaning for your integration
Resource	A publication or integration context. Its public key selects settings, catalog and resource-scoped records; it is not a secret.
User / member	The person whose identity or account is involved. A stored user record or activity flag is not a completed sign-in or a content-access decision.
Plan	A group of access rules with many Pricings. Displaying its rules does not grant access.
Pricing	A configured catalog choice under a Plan, with price, currency and period. Existing subscription routes/keys keep their literal names when selecting it.
Membership	A user’s existing relationship with a Plan/Pricing, including dates and renewal choices. Its relationship ID differs from the Pricing ID.

Read catalog and access concepts for the relationship map and operation-specific selection rules. Keep local Wallkit IDs, provider IDs and credentials separate.

Choose a path

Your job	Start here	Context to have already
Display catalog choices without signing in a member	Public plan list	Supplied API base and resource public key. No member token required for this call.
Identify a member and decide article access	Ordinary identity-to-access, or Firebase identity for that configured integration	Resource plus the selected identity flow; subsequent member calls use the returned/existing Wallkit token. Firebase ID tokens are separate.
Register a missing publisher item and check access	Sync-and-check reference	Enabled resource setting, intended creation, visitor context, and publisher type/title/link. The reference starts with a minimal request and then classification examples.
Explain or change a member’s account	Profile, User subscriptions and Pricing selection or team/pass/sponsorship choices	Existing member context and the exact operation’s target/ownership prerequisites.
Reconcile externally completed purchases or read assigned attendees	Server-integrations (advanced)	Existing authorized resource service account and exact action grant. Server user activity is a separate guest operation.
Manage provider preferences or a provider connection	3rd party integration flows or payment-source setup	Existing configured provider/resource integration and the permitted Wallkit actor. Stripe connection OAuth requires authorized admin context; ordinary provider preferences have different permissions.

Guest catalog discovery, guest content access and public event submission have different requirements. A resource public key is enough for the plan-list example below; a guest access decision needs its documented guest-session/configuration context. A member token does not grant every administrator/service action. Use credential transport for the exact headers, including trusted-server service-api-key and operation-specific Firebase handling.

Prepare the selected request

Use the API address and configuration supplied for your integration. WALLKIT_API_BASE contains only the scheme and host; examples add /api/v1. RESOURCE_KEY is the selected resource public key. Add USER_TOKEN, SERVICE_API_KEY or other credentials only when the operation requires them. Ask your integration owner for keys and the appropriate setup or session-refresh flow.

Each reference states the method/path, required context, body/query encoding, exact response fields and recovery. Examples use cURL, Node.js fetch and Python urllib; Node examples with top-level await use .mjs. Values are synthetic and requests are unexecuted. See sample runtimes.

Example reading path: display catalog choices

Choose GET /api/v1/plans. With the supplied resource key, its equivalent requests ask for page 1 and limit 10:

curl "${WALLKIT_API_BASE}/api/v1/plans?page=1&limit=10" \
  -H "resource: ${RESOURCE_KEY}"

const url = new URL("/api/v1/plans", process.env.WALLKIT_API_BASE);
url.searchParams.set("page", "1");
url.searchParams.set("limit", "10");
const response = await fetch(url, {
  method: "GET", headers: { resource: process.env.RESOURCE_KEY }
});
console.log(response.status, await response.json());

import os, json
from urllib.parse import urlencode, urljoin
from urllib.request import Request, urlopen
from urllib.error import HTTPError

url = urljoin(os.environ["WALLKIT_API_BASE"], "/api/v1/plans")
url += "?" + urlencode({"page": "1", "limit": "10"})
request = Request(url, headers={"resource": os.environ["RESOURCE_KEY"]}, method="GET")
try:
    with urlopen(request) as response:
        print(response.status, json.load(response))
except HTTPError as error:
    print(error.code, json.load(error))

A synthetic HTTP 200 excerpt pairs Plan ID 1001 with Pricing ID 2001:

{"items":[{"id":1001,"title":"Reader plan","subscriptions":[{"id":2001,"title":"Monthly","price":1200,"currency":"USD","period":"1 month"}]}],"paginator":{"current_page":1,"page":1,"total_pages":1,"total_items":1,"limit":10}}

Use the Plan and Pricing labels to present catalog choices. The amount’s scale is unspecified; do not infer cents from 1200. The public list’s visibility rules differ from known-plan detail. See the exact Plan and list relationship fields before building the display.

An empty items array is an ordinary result; show an empty state and check the selected resource and filters if unexpected. HTTP 404 resource_not_exists instead means the resource key did not resolve: confirm it with the integration owner. This catalog result creates no membership and is not permission to serve protected content.

Interpret the result before choosing the next task

What you receive	Decision
Catalog or account record	Use it to display or reconcile the requested records. Get a separate decision before serving protected content.
HTTP 200 with allow:false	Handle the denial using its reason/message. HTTP success is not content permission.
success:true, result:true or a recorded transaction status	Read the operation’s meaning. It may acknowledge a local write or an event attempt, without proving provider completion or delivery.
Empty collection, null, omitted field or false	Follow the exact projection and alternate result; these meanings differ by operation.
API error or no response	Use the operation’s recovery table. A network failure or error after writes may leave an uncertain outcome; do not blindly retry.

Some GETs record views, synchronize provider state or update service sessions and audit records. List wrappers and pagination differ by operation. Do not assume one rate limit or retry rule applies to every call. Response guidance explains how to identify the shape; the operation supplies the actual limits and consequences. Binary invoice/receipt reads need status and media-type handling instead of universal JSON parsing.

For the catalog example, continue to a selected Plan/Pricing reference when you need its details. Choose User subscriptions and Pricing selection only if payment/account work is intended. When serving an article, establish the documented visitor context and obtain the separate content-access decision. For another job, return to the grouped task index.