Manage sponsorship records and slots

List the current sponsor’s sponsorships

GET /api/v1/sponsor/sponsored-subscriptions

Inspect existing sponsorship records owned by the current person.

Before you call

Use member/record context. Selection joins configured Pricing/Plan, requires sponsor_id=current user and Plan.resource_id=selected resource. There is no active/expiry/activation filter. Records sort created_at descending, without a secondary tie order or pagination. No handler-specific payment/account mutation.

Request

Bodyless. No pagination/filter parameters are implemented.

Result

HTTP 200 JSON:

curl "${WALLKIT_API_BASE}/api/v1/sponsor/sponsored-subscriptions" \
  -H "resource: ${RESOURCE_KEY}" \
  -H "token: ${USER_TOKEN}"

const response = await fetch(`${process.env.WALLKIT_API_BASE}/api/v1/sponsor/sponsored-subscriptions`, {
  method: "GET", headers: { "resource": process.env.RESOURCE_KEY, "token": process.env.USER_TOKEN }
});
console.log(response.status, await response.json());

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

request = Request(os.environ["WALLKIT_API_BASE"] + "/api/v1/sponsor/sponsored-subscriptions",
    headers={"resource": os.environ["RESOURCE_KEY"], "token": os.environ["USER_TOKEN"]}, 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": 8001,
      "sponsor_id": 4001,
      "subscription_id": 2001,
      "slots": []
    }
  ]
}

{
  "items": []
}

Read one sponsorship owned by the current sponsor

GET /api/v1/sponsor/sponsored-subscriptions/{id}

Resolve an existing parent sponsorship and its nested slot/account summaries.

Before you call

Use member/record context. Integer-sanitized ID must be nonempty. Selection includes parent ID/current sponsor/Plan resource; no expiry or activation restriction. Missing/other-sponsor/wrong-resource parent returns HTTP 404. No action-specific writes.

Request

Bodyless. No pagination/filter parameters are implemented.

Result

HTTP 200 JSON:

curl "${WALLKIT_API_BASE}/api/v1/sponsor/sponsored-subscriptions/8001" \
  -H "resource: ${RESOURCE_KEY}" \
  -H "token: ${USER_TOKEN}"

const response = await fetch(`${process.env.WALLKIT_API_BASE}/api/v1/sponsor/sponsored-subscriptions/8001`, {
  method: "GET", headers: { "resource": process.env.RESOURCE_KEY, "token": process.env.USER_TOKEN }
});
console.log(response.status, await response.json());

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

request = Request(os.environ["WALLKIT_API_BASE"] + "/api/v1/sponsor/sponsored-subscriptions/8001",
    headers={"resource": os.environ["RESOURCE_KEY"], "token": os.environ["USER_TOKEN"]}, method="GET")
try:
    with urlopen(request) as response:
        print(response.status, json.load(response))
except HTTPError as error:
    print(error.code, json.load(error))

{
  "item": {
    "id": 8001,
    "sponsor_id": 4001,
    "subscription_id": 2001,
    "autorenew": null,
    "slots": []
  }
}

{
  "error": "sponsor_subscription_error",
  "error_description": "Sponsor subscription not found"
}

Update sponsorship text and payment preferences

PUT /api/v1/sponsor/sponsored-subscriptions/{id}

Change supported parent fields and first-associated membership renewal preferences.

Before you call

Use member/record context. The parent must match the current sponsor and the selected Pricing Plan’s resource. Supplied title/description must pass presence/length validation before string/trim filtering. Null or empty text is not an erase instruction; omitted fields are unchanged.

Changes run in this order, without an enclosing transaction:

1. Save supplied text and attempt its update event.
2. Save the parent’s is_paying_by_sponsor flag and attempt its event.
3. Save the first associated membership’s autorenew flag and attempt its event.
4. Save that membership’s is_allowed_next_subscription flag and attempt its event.

A strictly unchanged flag skips its step. The membership is selected by sponsored_subscription_id alone, without ordering or user/slot selection. These edits do not promise changes to every dependent membership.

Save results are unchecked. Membership saves attempt user/resource cache invalidation. No immediate charge, refund, membership deletion or expiry occurs. A later failure can follow earlier saved changes and events.

Request

Truthy JSON object required; Content-Type: application/json.

Result

HTTP 200 JSON:

curl -X PUT "${WALLKIT_API_BASE}/api/v1/sponsor/sponsored-subscriptions/8001" \
  -H "resource: ${RESOURCE_KEY}" \
  -H "token: ${USER_TOKEN}" \
  -H "Content-Type: application/json" \
  --data-raw '{"title": "Example sponsor group", "autorenew": false}'

const response = await fetch(`${process.env.WALLKIT_API_BASE}/api/v1/sponsor/sponsored-subscriptions/8001`, {
  method: "PUT", headers: { "resource": process.env.RESOURCE_KEY, "token": process.env.USER_TOKEN, "Content-Type": "application/json" },
  body: JSON.stringify({"title": "Example sponsor group", "autorenew": false})
});
console.log(response.status, await response.json());

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

body = {'title': 'Example sponsor group', 'autorenew': False}
request = Request(os.environ["WALLKIT_API_BASE"] + "/api/v1/sponsor/sponsored-subscriptions/8001",
    data=json.dumps(body).encode("utf-8"), headers={"resource": os.environ["RESOURCE_KEY"], "token": os.environ["USER_TOKEN"], "Content-Type": "application/json"}, method="PUT")
try:
    with urlopen(request) as response:
        print(response.status, json.load(response))
except HTTPError as error:
    print(error.code, json.load(error))

{
  "item": {
    "id": 8001,
    "title": "Example sponsor group",
    "autorenew": false
  }
}

{
  "error": "sponsor_subscription_update_error",
  "error_description": "Update sponsor subscription relationship autorenew status has failed"
}

List slots for an owned sponsorship

GET /api/v1/sponsor/sponsored-subscriptions/{id}/slots

Inspect all slots belonging to one selected parent.

Before you call

Use member/record context. Parent ownership/Plan resource is checked first. Slot selection uses that parent ID and sorts created_at descending; no activation/recipient/expiry filter and no paginator. No action-specific writes.

Request

Bodyless. No pagination/filter parameters are implemented.

Result

HTTP 200 JSON:

curl "${WALLKIT_API_BASE}/api/v1/sponsor/sponsored-subscriptions/8001/slots" \
  -H "resource: ${RESOURCE_KEY}" \
  -H "token: ${USER_TOKEN}"

const response = await fetch(`${process.env.WALLKIT_API_BASE}/api/v1/sponsor/sponsored-subscriptions/8001/slots`, {
  method: "GET", headers: { "resource": process.env.RESOURCE_KEY, "token": process.env.USER_TOKEN }
});
console.log(response.status, await response.json());

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

request = Request(os.environ["WALLKIT_API_BASE"] + "/api/v1/sponsor/sponsored-subscriptions/8001/slots",
    headers={"resource": os.environ["RESOURCE_KEY"], "token": os.environ["USER_TOKEN"]}, 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": 9001,
      "sponsored_subscription_id": 8001,
      "recipient_id": null,
      "recipient_email": null,
      "activated_at": null
    }
  ]
}

{
  "items": []
}

Read one slot under an owned sponsorship

GET /api/v1/sponsor/sponsored-subscriptions/slots/{id}

Read base slot state after checking ownership/resource through its parent.

Before you call

Use member/record context. Slot is initially fetched by its ID, then its parent sponsorship must pass current sponsor/Plan-resource selection. No activation/expiry restriction or action-specific writes.

Request

Bodyless. No pagination/filter parameters are implemented.

Result

HTTP 200 JSON:

curl "${WALLKIT_API_BASE}/api/v1/sponsor/sponsored-subscriptions/slots/9001" \
  -H "resource: ${RESOURCE_KEY}" \
  -H "token: ${USER_TOKEN}"

const response = await fetch(`${process.env.WALLKIT_API_BASE}/api/v1/sponsor/sponsored-subscriptions/slots/9001`, {
  method: "GET", headers: { "resource": process.env.RESOURCE_KEY, "token": process.env.USER_TOKEN }
});
console.log(response.status, await response.json());

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

request = Request(os.environ["WALLKIT_API_BASE"] + "/api/v1/sponsor/sponsored-subscriptions/slots/9001",
    headers={"resource": os.environ["RESOURCE_KEY"], "token": os.environ["USER_TOKEN"]}, method="GET")
try:
    with urlopen(request) as response:
        print(response.status, json.load(response))
except HTTPError as error:
    print(error.code, json.load(error))

{
  "item": {
    "id": 9001,
    "sponsored_subscription_id": 8001,
    "recipient_email": "reader@example.com",
    "activation_code": "SLOT_ACTIVATION_CODE_PLACEHOLDER",
    "activated_at": null
  }
}

{
  "error": "sponsor_subscription_slot_error",
  "error_description": "Slot not found"
}

Invite or notify a sponsorship slot recipient

PUT /api/v1/sponsor/sponsored-subscriptions/slots/{id}/invitation

Store the intended recipient email and attempt configured notification events.

Before you call

Use member/record context. The slot’s parent must match the current sponsor and Pricing Plan resource. An activated slot rejects changes. recipient_email must be present and email-valid; the sanitized value is stored in lowercase without an explicit trim step.

Code behavior: changing a nonempty stored email to a different lowercase email generates a new unique 16-character activation code. An empty prior email or the same email retains the stored code. A same-email request can attempt notifications again; it is not deduplicated by a documented guarantee.

Save and notification: the save result is unchecked, then the slot is refreshed. Generic and gift/multi-seat invitation events are attempted afterward. An unsupported Pricing type or event failure can therefore follow an email change.

The action does not bind recipient_id, activate membership, set expiry or charge payment. There is no enclosing transaction or delivered-email guarantee.

Request

Truthy JSON object required, Content-Type: application/json.

Result

HTTP 200 JSON:

curl -X PUT "${WALLKIT_API_BASE}/api/v1/sponsor/sponsored-subscriptions/slots/9001/invitation" \
  -H "resource: ${RESOURCE_KEY}" \
  -H "token: ${USER_TOKEN}" \
  -H "Content-Type: application/json" \
  --data-raw '{"recipient_email": "reader@example.com"}'

const response = await fetch(`${process.env.WALLKIT_API_BASE}/api/v1/sponsor/sponsored-subscriptions/slots/9001/invitation`, {
  method: "PUT", headers: { "resource": process.env.RESOURCE_KEY, "token": process.env.USER_TOKEN, "Content-Type": "application/json" },
  body: JSON.stringify({"recipient_email": "reader@example.com"})
});
console.log(response.status, await response.json());

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

body = {'recipient_email': 'reader@example.com'}
request = Request(os.environ["WALLKIT_API_BASE"] + "/api/v1/sponsor/sponsored-subscriptions/slots/9001/invitation",
    data=json.dumps(body).encode("utf-8"), headers={"resource": os.environ["RESOURCE_KEY"], "token": os.environ["USER_TOKEN"], "Content-Type": "application/json"}, method="PUT")
try:
    with urlopen(request) as response:
        print(response.status, json.load(response))
except HTTPError as error:
    print(error.code, json.load(error))

{
  "item": {
    "id": 9001,
    "sponsored_subscription_id": 8001,
    "recipient_email": "reader@example.com",
    "activation_code": "SLOT_ACTIVATION_CODE_PLACEHOLDER",
    "activated_at": null
  }
}

{
  "error": "sponsor_subscription_slot_error",
  "error_description": "Sponsor subscription slot invitation has failed"
}

Clear an owned multi-seat sponsorship slot

PUT /api/v1/sponsor/sponsored-subscriptions/slots/{id}/clear

Reset slot recipient/invitation state and attempt deletion of its first linked membership.

Before you call

Use active sponsor/resource context. The slot ID is integer-cast. Inside a database transaction, the Pricing Plan’s resource and parent sponsor_id must strictly match the supplied context. Pricing must be multi-seat; gift slots are excluded. There is no explicit parent-expiry or slot-active guard.

Slot reset: the action clears recipient_id, recipient_email and activated_at, generates a fresh activation code and attempts an unchecked save.

Membership cleanup: it deletes the first membership found by sponsored_subscription_slot_id and writes history. Neither result is checked; this does not remove every matching or dependent membership. Deletion attempts user/resource cache invalidation. If the Plan resource enables auto_clear_content_views and the membership has a user ID, the deletion hook also attempts removal of all that user’s content-view records without resource filtering. It does not delete the user or issue a refund.

Completion: the action commits and prepares success/item, then attempts a slot-update event outside its error-handling block. An event failure can follow committed writes without a stable action-specific error response. Local rollback does not guarantee reversal of nested, hook or external effects.

Request

Bodyless; no action JSON fields consumed.

Result

HTTP 200 JSON:

curl -X PUT "${WALLKIT_API_BASE}/api/v1/sponsor/sponsored-subscriptions/slots/9001/clear" \
  -H "resource: ${RESOURCE_KEY}" \
  -H "token: ${USER_TOKEN}"

const response = await fetch(`${process.env.WALLKIT_API_BASE}/api/v1/sponsor/sponsored-subscriptions/slots/9001/clear`, {
  method: "PUT", headers: { "resource": process.env.RESOURCE_KEY, "token": process.env.USER_TOKEN }
});
console.log(response.status, await response.json());

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

request = Request(os.environ["WALLKIT_API_BASE"] + "/api/v1/sponsor/sponsored-subscriptions/slots/9001/clear",
    headers={"resource": os.environ["RESOURCE_KEY"], "token": os.environ["USER_TOKEN"]}, method="PUT")
try:
    with urlopen(request) as response:
        print(response.status, json.load(response))
except HTTPError as error:
    print(error.code, json.load(error))

{
  "success": true,
  "item": {
    "id": 9001,
    "sponsored_subscription_id": 8001,
    "recipient_id": null,
    "recipient_email": null,
    "activation_code": "NEW_SLOT_CODE_PLACEHOLDER",
    "activated_at": null
  }
}

{
  "error": "sponsored_subscription_type",
  "error_description": "Available to clear only multi-seat slots"
}

List invitation slots matching the current member’s email

GET /api/v1/recipient/sponsored-subscriptions/slots/invitations

Find pending stored invitations addressed to the current person’s email.

Before you call

Use member context. Selection compares recipient_email to current user.email exactly, joins Pricing Plan resource, requires activation_code IS NOT NULL, activated_at IS NULL and parent expired_at IS NULL. It does not require recipient_id=current user or check parent end dates, other active flags or future activation success. No ordering or pagination specified. No handler-specific account writes.

Request

Bodyless; no action pagination/filter parameters implemented.

Result

HTTP 200 JSON:

curl "${WALLKIT_API_BASE}/api/v1/recipient/sponsored-subscriptions/slots/invitations" \
  -H "resource: ${RESOURCE_KEY}" \
  -H "token: ${USER_TOKEN}"

const response = await fetch(`${process.env.WALLKIT_API_BASE}/api/v1/recipient/sponsored-subscriptions/slots/invitations`, {
  method: "GET", headers: { "resource": process.env.RESOURCE_KEY, "token": process.env.USER_TOKEN }
});
console.log(response.status, await response.json());

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

request = Request(os.environ["WALLKIT_API_BASE"] + "/api/v1/recipient/sponsored-subscriptions/slots/invitations",
    headers={"resource": os.environ["RESOURCE_KEY"], "token": os.environ["USER_TOKEN"]}, 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": 9001,
      "recipient_email": "reader@example.com",
      "activation_code": "SLOT_ACTIVATION_CODE_PLACEHOLDER",
      "sponsored_subscription": {
        "id": 8001,
        "subscription_id": 2001
      }
    }
  ]
}

{
  "items": []
}

Activate a sponsorship slot using its code

PUT /api/v1/recipient/sponsored-subscriptions/slots/activate

Attempt the selected slot’s membership activation for the current active person.

Before you call

Use member context and the existing issuer-provided code. It must remain nonempty after string/trim filtering. Code lookup is exact and initially has no email/resource predicate.

Acceptance checks: the slot must not have an activation marker, and its Pricing Plan must strictly match the selected resource. recipient_id is compared with the current member only when already nonempty. The action does not compare recipient_email or reject a parent expired_at marker. An unbound slot can therefore pass the identity check for a member who holds the code; email-matched listing does not strengthen this guard.

Only gift and multi-seat Pricings are supported:

• Gift: creates or replaces recipient membership with sponsorship/slot IDs. Pricing trial settings are checked first; the shared helper applies trial only if the person’s current/history trial eligibility also passes. Parent activated_at is then saved.
• Multi-seat: requires a first parent membership with the sponsorship ID, null parent_id and null user_id. Recipient membership uses that parent ID and slot ID, null sponsored_subscription_id, the copied parent end date and trial=false.

The membership helper can replace prior memberships, write history, stop/clear other sponsorships and attempt cache, content-view, event and synchronization effects. Deletion hooks can conditionally clear user content-view records across resources.

The slot’s recipient and activation time are set, and its code is cleared, without checking save success. Gift parent save is also unchecked. Sponsor/recipient events follow. There is no transaction covering the entire action; nested helper transactions do not make later slot, parent or event writes atomic or safe to repeat.

Request

Truthy JSON object required, Content-Type: application/json.

Result

HTTP 200 JSON:

curl -X PUT "${WALLKIT_API_BASE}/api/v1/recipient/sponsored-subscriptions/slots/activate" \
  -H "resource: ${RESOURCE_KEY}" \
  -H "token: ${USER_TOKEN}" \
  -H "Content-Type: application/json" \
  --data-raw '{"activation_code": "SLOT_ACTIVATION_CODE_PLACEHOLDER"}'

const response = await fetch(`${process.env.WALLKIT_API_BASE}/api/v1/recipient/sponsored-subscriptions/slots/activate`, {
  method: "PUT", headers: { "resource": process.env.RESOURCE_KEY, "token": process.env.USER_TOKEN, "Content-Type": "application/json" },
  body: JSON.stringify({"activation_code": "SLOT_ACTIVATION_CODE_PLACEHOLDER"})
});
console.log(response.status, await response.json());

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

body = {'activation_code': 'SLOT_ACTIVATION_CODE_PLACEHOLDER'}
request = Request(os.environ["WALLKIT_API_BASE"] + "/api/v1/recipient/sponsored-subscriptions/slots/activate",
    data=json.dumps(body).encode("utf-8"), headers={"resource": os.environ["RESOURCE_KEY"], "token": os.environ["USER_TOKEN"], "Content-Type": "application/json"}, method="PUT")
try:
    with urlopen(request) as response:
        print(response.status, json.load(response))
except HTTPError as error:
    print(error.code, json.load(error))

{
  "success": true,
  "item": {
    "id": 9001,
    "recipient_id": 4002,
    "recipient_email": "reader@example.com",
    "activation_code": null,
    "sponsored_subscription": {
      "id": 8001,
      "subscription_id": 2001
    }
  }
}

{
  "error": "sponsor_subscription_slot_error",
  "error_description": "Slot not found"
}

Turn off sponsor payment for a gift slot

PUT /api/v1/recipient/sponsored-subscriptions/slots/{id}/sponsor/turn-off

Attempt to disable the parent gift sponsorship’s payer flag.

Before you call

Use active member/resource context. The slot is fetched without an initial owner/email predicate. Pricing must be gift, and its Plan resource must strictly match. The current person is checked against recipient_id only when that field is nonempty. Email, activation time and parent expiry are not checked.

Payer change: an already-false parent is_paying_by_sponsor flag rejects the request. Otherwise the helper sets it false and attempts an unchecked save. General helper failures can be logged and swallowed.

Later effects: mapping and sponsor/recipient event attempts follow without an enclosing transaction. An unbound slot can pass the earlier identity check, then fail the recipient-empty event check after the parent mutation attempt. An error therefore does not prove unchanged state.

This action does not refund, expire or delete membership, configure a recipient payment source or charge payment. A later charging helper uses the flag to choose sponsor versus member; it does not guarantee successful future collection.

Request

Bodyless; no action JSON fields consumed.

Result

HTTP 200 JSON:

curl -X PUT "${WALLKIT_API_BASE}/api/v1/recipient/sponsored-subscriptions/slots/9001/sponsor/turn-off" \
  -H "resource: ${RESOURCE_KEY}" \
  -H "token: ${USER_TOKEN}"

const response = await fetch(`${process.env.WALLKIT_API_BASE}/api/v1/recipient/sponsored-subscriptions/slots/9001/sponsor/turn-off`, {
  method: "PUT", headers: { "resource": process.env.RESOURCE_KEY, "token": process.env.USER_TOKEN }
});
console.log(response.status, await response.json());

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

request = Request(os.environ["WALLKIT_API_BASE"] + "/api/v1/recipient/sponsored-subscriptions/slots/9001/sponsor/turn-off",
    headers={"resource": os.environ["RESOURCE_KEY"], "token": os.environ["USER_TOKEN"]}, method="PUT")
try:
    with urlopen(request) as response:
        print(response.status, json.load(response))
except HTTPError as error:
    print(error.code, json.load(error))

{
  "item": {
    "id": 9001,
    "recipient_id": 4002,
    "sponsored_subscription": {
      "id": 8001,
      "is_paying_by_sponsor": false
    }
  }
}

{
  "error": "sponsor_subscription_slot_error",
  "error_description": "Sponsored subscription slot recipient is empty"
}