Catalog

List the user’s plans

GET /api/v1/user/plans

List distinct plans attached to this user through subscription membership in the selected resource. This is the member’s catalog, not the public Pricing list. The selection does not add an active/private plan filter.

Before you call

Use an existing member token. A matching membership must exist to produce an item; obtaining a Pricing ID alone is not enough. See catalog context for supplied configuration and shared checks.

Request

GET with no request body or request Content-Type requirement. Response media type is JSON. Requires the user role or inherited permission and active member context. See credential transport.

Filters span Plans, Subscriptions and UserPlanRelationships. Sorting defaults to Plans.created_at DESC; order overrides by. Only one membership is serialized per plan even if several matching relationships exist.

Result

HTTP 200 JSON.

paginator uses the collection fields. An empty collection is an ordinary result; do not interpret it as an authentication failure.

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

// Node.js 18+; built-in fetch. Supply existing integration configuration.
async function main() {
  const url = new URL("/api/v1/user/plans", process.env.WALLKIT_API_BASE);
  url.searchParams.set("page", "1");
  url.searchParams.set("limit", "10");
  const headers = { resource: process.env.RESOURCE_KEY, token: process.env.USER_TOKEN };
  const response = await fetch(url, { method: "GET", headers });
  const body = await response.json();
  console.log(response.status, body);
}
main().catch(console.error);

# Python 3; standard library only.
import json
import os
from urllib.error import HTTPError
from urllib.parse import urlencode, urljoin
from urllib.request import Request, urlopen

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

{
  "items": [
    {
      "id": 1001,
      "title": "Reader plan",
      "slug": "reader",
      "active": true,
      "private": false,
      "subscription": {
        "id": 2001,
        "title": "Monthly",
        "price": 1200,
        "currency": "USD",
        "period": "1 month",
        "subscription_end_date": "2026-12-01 00:00:00",
        "autorenew": true,
        "is_team_subscription": false
      }
    }
  ]
}

{
  "items": []
}

List available team plans

GET /api/v1/user/teams/{team_id}/plans

Find child plans reachable from this user’s plan relationships for team subscriptions. The team ID must exist; the selection itself is based on user-plan relationships, not a team-specific membership filter. Parent and child plans must be active, and child plans cannot themselves own teams.

Before you call

Use an existing member token and team ID from your integration’s team record. The team must exist. Selection follows the user’s linked plans; it does not prove ownership of that team or restrict the selection by the supplied team ID. See catalog context for supplied configuration and shared checks.

Request

GET with no request body or request Content-Type requirement. Response media type is JSON. Requires the user role or inherited permission and active member context. See credential transport.

No explicit sorting option or team ownership validation is added by this operation. Do not use this list as proof that the caller owns the given team.

Result

HTTP 200 JSON.

paginator uses the collection fields. An empty collection is an ordinary result; do not interpret it as an authentication failure.

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

// Node.js 18+; built-in fetch. Supply existing integration configuration.
async function main() {
  const url = new URL("/api/v1/user/teams/3001/plans", process.env.WALLKIT_API_BASE);
  url.searchParams.set("page", "1");
  url.searchParams.set("limit", "10");
  const headers = { resource: process.env.RESOURCE_KEY, token: process.env.USER_TOKEN };
  const response = await fetch(url, { method: "GET", headers });
  const body = await response.json();
  console.log(response.status, body);
}
main().catch(console.error);

# Python 3; standard library only.
import json
import os
from urllib.error import HTTPError
from urllib.parse import urlencode, urljoin
from urllib.request import Request, urlopen

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

{
  "items": [
    {
      "id": 1001,
      "title": "Reader plan",
      "slug": "reader",
      "active": true,
      "private": false,
      "subscriptions": [
        {
          "id": 2001,
          "title": "Monthly",
          "price": 1200,
          "currency": "USD",
          "period": "1 month",
          "users_limit": 5
        }
      ]
    }
  ]
}

{
  "items": []
}

Read the embedded integration catalog

GET /api/v1/integrations/plans

Load the resource-scoped plan/subscription catalog used by embedded integrations. Prefer the public plan list when you need its explicit active/private visibility rules.

Before you call

Use the resource public key supplied for the embedded integration. No member token is required. Missing resource context is not rejected, but cannot produce a useful catalog. See catalog context for supplied configuration and shared checks.

Request

GET with no request body or request Content-Type requirement. Response media type is JSON. Permits guest access with the context described above. See credential transport.

Supply resource for useful results, although this operation does not reject missing resource context. Results are grouped by plan and ordered by plan title ascending. No pagination, filter or sort parameters are read. Active-only selection is not guaranteed for this legacy selector.

Result

HTTP 200 JSON.

No pagination. Missing resource context returns items: []; a resolved resource with no plans can leave items absent. Handle both, rather than assuming one fixed empty shape.

curl "${WALLKIT_API_BASE}/api/v1/integrations/plans" \
  -H "resource: ${RESOURCE_KEY}"

// Node.js 18+; built-in fetch. Supply existing integration configuration.
async function main() {
  const url = new URL("/api/v1/integrations/plans", process.env.WALLKIT_API_BASE);
  const headers = { resource: process.env.RESOURCE_KEY };
  const response = await fetch(url, { method: "GET", headers });
  const body = await response.json();
  console.log(response.status, body);
}
main().catch(console.error);

# Python 3; standard library only.
import json
import os
from urllib.error import HTTPError
from urllib.parse import urlencode, urljoin
from urllib.request import Request, urlopen

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

{
  "items": [
    {
      "id": 1001,
      "title": "Reader plan",
      "slug": "reader",
      "active": true,
      "private": false,
      "subscriptions": [
        {
          "id": 2001,
          "title": "Monthly",
          "price": 1200,
          "currency": "USD",
          "period": "1 month"
        }
      ]
    }
  ]
}

{
  "items": []
}

List public plans

GET /api/v1/plans

List active, non-private plans in the selected resource that have active, non-private subscriptions. A validated invite may include its private subscription and associated private plan.

Before you call

Use the resource public key supplied for your integration. No member token is required. Have an invite code only when your integration already supplies one; these docs do not issue invites. See catalog context for supplied configuration and shared checks.

Request

GET with no request body or request Content-Type requirement. Response media type is JSON. Permits guest access with the context described above. See credential transport.

Result

HTTP 200 JSON.

paginator uses the collection fields. An empty collection is an ordinary result; do not interpret it as an authentication failure.

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

// Node.js 18+; built-in fetch. Supply existing integration configuration.
async function main() {
  const url = new URL("/api/v1/plans", process.env.WALLKIT_API_BASE);
  url.searchParams.set("page", "1");
  url.searchParams.set("limit", "10");
  const headers = { resource: process.env.RESOURCE_KEY };
  const response = await fetch(url, { method: "GET", headers });
  const body = await response.json();
  console.log(response.status, body);
}
main().catch(console.error);

# Python 3; standard library only.
import json
import os
from urllib.error import HTTPError
from urllib.parse import urlencode, urljoin
from urllib.request import Request, urlopen

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

{
  "items": [
    {
      "id": 1001,
      "title": "Reader plan",
      "slug": "reader",
      "active": true,
      "private": false,
      "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
  }
}

{
  "items": []
}

Get a plan

GET /api/v1/plans/{id}

Read a known plan in the selected resource. Unlike the list, this lookup does not require the plan or its subscriptions to be active/non-private.

Before you call

Take the plan ID from the plan list or an existing integration record. It must belong to the selected resource. A private/inactive detail record is not proof of purchase eligibility. See catalog context for supplied configuration and shared checks.

Request

GET with no request body or request Content-Type requirement. Response media type is JSON. Permits guest access with the context described above. See credential transport.

Result

HTTP 200 JSON.

curl "${WALLKIT_API_BASE}/api/v1/plans/1001" \
  -H "resource: ${RESOURCE_KEY}"

// Node.js 18+; built-in fetch. Supply existing integration configuration.
async function main() {
  const url = new URL("/api/v1/plans/1001", process.env.WALLKIT_API_BASE);
  const headers = { resource: process.env.RESOURCE_KEY };
  const response = await fetch(url, { method: "GET", headers });
  const body = await response.json();
  console.log(response.status, body);
}
main().catch(console.error);

# Python 3; standard library only.
import json
import os
from urllib.error import HTTPError
from urllib.parse import urlencode, urljoin
from urllib.request import Request, urlopen

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

{
  "id": 1001,
  "title": "Reader plan",
  "slug": "reader",
  "active": true,
  "private": false,
  "subscriptions": [
    {
      "id": 2001,
      "title": "Monthly",
      "price": 1200,
      "currency": "USD",
      "period": "1 month"
    }
  ]
}

{
  "error": "plan_not_found",
  "error_description": "Plan not found",
  "req_guid": "example-request"
}

List public Pricings

GET /api/v1/subscriptions

List active public subscriptions whose parent plans are active and public in the selected resource. This lists Pricings, not user memberships.

Before you call

Use the resource public key. A member token is optional for user-specific cascade information; without it the example is a guest-readable Pricing list. See catalog context for supplied configuration and shared checks.

Request

GET with no request body or request Content-Type requirement. Response media type is JSON. Permits guest access with the context described above. See credential transport.

A token is optional when you want user-specific cascade context; this read does not create a membership.

Result

HTTP 200 JSON.

paginator uses the collection fields. An empty collection is an ordinary result; do not interpret it as an authentication failure.

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

// Node.js 18+; built-in fetch. Supply existing integration configuration.
async function main() {
  const url = new URL("/api/v1/subscriptions", process.env.WALLKIT_API_BASE);
  url.searchParams.set("page", "1");
  url.searchParams.set("limit", "10");
  const headers = { resource: process.env.RESOURCE_KEY };
  const response = await fetch(url, { method: "GET", headers });
  const body = await response.json();
  console.log(response.status, body);
}
main().catch(console.error);

# Python 3; standard library only.
import json
import os
from urllib.error import HTTPError
from urllib.parse import urlencode, urljoin
from urllib.request import Request, urlopen

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

{
  "items": [
    {
      "id": 2001,
      "title": "Monthly",
      "price": 1200,
      "currency": "USD",
      "period": "1 month",
      "plan": {
        "id": 1001,
        "title": "Reader plan"
      },
      "applied_cascade_access": false
    }
  ]
}

{
  "items": []
}

Get a Pricing

GET /api/v1/subscriptions/{id}

Read a known subscription whose parent plan belongs to the selected resource. Unlike the list, this lookup does not add active/private checks.

Before you call

Take the Pricing ID from a subscription list or existing integration record. Use a nonzero ID belonging to a plan in this resource. See catalog context for supplied configuration and shared checks.

Request

GET with no request body or request Content-Type requirement. Response media type is JSON. Permits guest access with the context described above. See credential transport.

Result

HTTP 200 JSON.

curl "${WALLKIT_API_BASE}/api/v1/subscriptions/2001" \
  -H "resource: ${RESOURCE_KEY}"

// Node.js 18+; built-in fetch. Supply existing integration configuration.
async function main() {
  const url = new URL("/api/v1/subscriptions/2001", process.env.WALLKIT_API_BASE);
  const headers = { resource: process.env.RESOURCE_KEY };
  const response = await fetch(url, { method: "GET", headers });
  const body = await response.json();
  console.log(response.status, body);
}
main().catch(console.error);

# Python 3; standard library only.
import json
import os
from urllib.error import HTTPError
from urllib.parse import urlencode, urljoin
from urllib.request import Request, urlopen

url = urljoin(os.environ["WALLKIT_API_BASE"], "/api/v1/subscriptions/2001")
headers = {"resource": os.environ["RESOURCE_KEY"]}
request = Request(url, headers=headers, method="GET")
try:
    with urlopen(request) as response:
        print(response.status, json.load(response))
except HTTPError as error:
    print(error.code, json.load(error))

{
  "id": 2001,
  "title": "Monthly",
  "price": 1200,
  "currency": "USD",
  "period": "1 month",
  "active": true,
  "private": false,
  "public": true,
  "plan": {
    "id": 1001,
    "title": "Reader plan",
    "subscriptions": [
      {
        "id": 2001,
        "title": "Monthly",
        "price": 1200,
        "currency": "USD",
        "period": "1 month"
      }
    ]
  }
}

{
  "error": "subscription_not_found",
  "error_description": "Subscription not found",
  "req_guid": "example-request"
}