External purchase records

Resolve an externally mapped Pricing

GET /api/v1/integrations/external/subscription

Resolve a complete token in a Pricing’s comma-separated external_source_ids within the selected resource. The API retains subscription naming; the returned subscription is a Pricing, not a membership. No purchase or provider payment is performed.

Before you call

Use a configured external-source identifier already mapped to a Pricing in the selected resource. It is compared case-insensitively after trimming, following a case-insensitive substring prefilter; the final comparison is a complete comma-separated token. Matching does not require active or public Pricing status, user ownership or a paid membership. Multiple mapped matches have no unique-selection or ordering guarantee; a later match can replace an earlier one.

Use the shared service-account context and the grant for this exact action.

This controller also requires an active resolved user and valid resource. A locked/suspended attached resource relationship, when present, fails the shared user checks.

Request

Bodyless GET.

Examples use the safely encoded synthetic token catalog-reader-monthly. No provider/source type selector is required by this action.

Result

HTTP 200 returns subscription as the general Pricing projection, including its compact plan and conditional administrative fields.

Stored price units, currency normalization, timestamp timezone and a complete type enum are unspecified. Reading the Pricing does not grant entitlement or collect money.

curl "${WALLKIT_API_BASE}/api/v1/integrations/external/subscription?external_source_id=catalog-reader-monthly" \
  -H "resource: ${RESOURCE_KEY}" \
  -H "service-api-key: ${SERVICE_API_KEY}"

const response = await fetch(`${process.env.WALLKIT_API_BASE}/api/v1/integrations/external/subscription?external_source_id=catalog-reader-monthly`, {
  method: "GET",
  headers: {"resource": process.env.RESOURCE_KEY, "service-api-key": process.env.SERVICE_API_KEY}
});
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/integrations/external/subscription?external_source_id=catalog-reader-monthly",
    headers={'resource': os.environ["RESOURCE_KEY"], 'service-api-key': os.environ["SERVICE_API_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))

{
  "subscription": {
    "id": 3001,
    "plan_id": 4001,
    "title": "Reader monthly",
    "external_source_ids": "catalog-reader-monthly,legacy-reader",
    "active": true,
    "private": false,
    "public": true,
    "next_subscription": null,
    "downgrade_subscription": null,
    "plan": {
      "id": 4001,
      "title": "Reader plan",
      "full_access": false
    }
  }
}

{
  "error": "subscription_not_found",
  "error_description": "Subscription not found"
}

Inspect a recorded external transaction

GET /api/v1/integrations/external/transaction

Find the first stored external transaction matching its external ID in the selected resource. This lookup has no target-user parameter or user ownership filter. It does not ask a payment provider for current settlement or refund status.

Before you call

Use the shared service-account context and the grant for this exact action.

An active resolved account user and valid resource are required; an attached resource relationship, when present, must not be locked or suspended.

Use the externally recorded transaction identifier, not the catalog mapping token or local transaction ID. Duplicate external IDs have no stable selection/order guarantee.

Request

Bodyless GET.

Result

HTTP 200 returns transaction with these base fields. It omits external transaction_id, data, json_data, purchases, timestamps, custom, is_external and expanded user/card/refund/receipt fields.

A succeeded status is a local recorded value. This read does not prove membership, provider completion or money returned.

curl "${WALLKIT_API_BASE}/api/v1/integrations/external/transaction?external_source_id=order-reader-1001" \
  -H "resource: ${RESOURCE_KEY}" \
  -H "service-api-key: ${SERVICE_API_KEY}"

const response = await fetch(`${process.env.WALLKIT_API_BASE}/api/v1/integrations/external/transaction?external_source_id=order-reader-1001`, {
  method: "GET",
  headers: {"resource": process.env.RESOURCE_KEY, "service-api-key": process.env.SERVICE_API_KEY}
});
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/integrations/external/transaction?external_source_id=order-reader-1001",
    headers={'resource': os.environ["RESOURCE_KEY"], 'service-api-key': os.environ["SERVICE_API_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))

{
  "transaction": {
    "id": 5001,
    "status": "succeeded",
    "user_id": 1001,
    "pay_system": "in-app",
    "amount": 1000,
    "currency": "USD",
    "amount_refunded": 0,
    "livemode": false
  }
}

{
  "error": "get_transaction_error",
  "error_description": "Transaction not found"
}

Record an external purchase for a user

POST /api/v1/integrations/users/{user_id}/external/subscriptions

Record an external membership, transaction and linked purchase for a user already related to the resource. Payment must be handled separately by the external system: this call records local succeeded/in-app data and does not collect money. It can replace memberships and change associated history, sponsorship and content-view records.

Before you call

Use the shared service-account context and the grant for this exact action.

An active resolved account user and valid resource are required; an attached resource relationship, when present, must not be locked or suspended.

The target user must exist globally and have a relationship with this resource; this target lookup does not itself check target activation, lock or suspension. Select a resource-owned Pricing by integer id or a complete mapped source_id. The first existing membership found in the resource blocks a selected lower-priced Pricing with Current subscription is Higher-Tier Price; this is not a comparison across all memberships.

Supply subscription and transaction as JSON objects. Malformed/null/scalar objects can fail before their validators, without a dependable action-specific HTTP error. Resolve external ID duplication and prior uncertain results before recording.

Request

JSON body with Content-Type: application/json.

Extra fields do not configure a provider, add a payment source or select a different target user. Subscription end_date and update’s later subscription_end_date are distinct inputs.

Result

Intended HTTP 201 returns success:true only; no membership, transaction or purchase IDs are returned.

Membership and recording effects

• An existing external membership for this user/Pricing is updated with the supplied end date and trial flag. This branch retains its existing autorenew value.
• Otherwise, the membership helper requires a Pricing period and can enforce configured once-use history. It replaces the existing membership for that Plan, records history, and creates an external membership with autorenew forced true. Requested trial status is subject to configured trial eligibility and prior/current trial history.
• With single_subscription enabled, other memberships in this resource can also be moved to history and deleted. Replacement/deletion can expire sponsored gifts or clear assigned multi-seat slots. Membership saves invalidate caches; deletion with auto_clear_content_views can clear the user’s content-view records without a resource predicate.
• The actor user is recorded as admin_id. The action then creates an external/custom transaction with status succeeded and pay_system in-app, plus a purchase whose item IDs select the Pricing and whose relation ID selects the membership. These are local records; no payment-source/provider charge is performed.
• The new-membership path attempts subscription/admin events and, with configured Campaign Monitor OAuth, synchronization before the outer action commit. The final external-recording event follows the outer commit. These attempts do not prove notification or queue delivery.

The helper uses a nested transaction and several saves are unchecked. A failure or success response cannot establish an all-or-nothing result. Missing/malformed transaction objects can fail after membership work. Duplicate transaction IDs are not rejected here; repeated POSTs can add transactions/purchases and repeat effects. Do not retry an uncertain result blindly.

curl -X POST "${WALLKIT_API_BASE}/api/v1/integrations/users/1001/external/subscriptions" \
  -H "resource: ${RESOURCE_KEY}" \
  -H "service-api-key: ${SERVICE_API_KEY}" \
  -H "Content-Type: application/json" \
  --data-raw '{"subscription": {"id": 3001, "end_date": "2026-11-01", "is_trial": false}, "transaction": {"id": "order-reader-1001", "is_live_mode": false, "amount": 1000, "currency": "USD", "data": "External purchase recorded by the integration"}}'

const response = await fetch(`${process.env.WALLKIT_API_BASE}/api/v1/integrations/users/1001/external/subscriptions`, {
  method: "POST",
  headers: {"resource": process.env.RESOURCE_KEY, "service-api-key": process.env.SERVICE_API_KEY, "Content-Type": "application/json"},
  body: JSON.stringify({"subscription": {"id": 3001, "end_date": "2026-11-01", "is_trial": false}, "transaction": {"id": "order-reader-1001", "is_live_mode": false, "amount": 1000, "currency": "USD", "data": "External purchase recorded by the integration"}})
});
console.log(response.status, await response.json());

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

body = {'subscription': {'id': 3001, 'end_date': '2026-11-01', 'is_trial': False}, 'transaction': {'id': 'order-reader-1001', 'is_live_mode': False, 'amount': 1000, 'currency': 'USD', 'data': 'External purchase recorded by the integration'}}
request = Request(os.environ["WALLKIT_API_BASE"] + "/api/v1/integrations/users/1001/external/subscriptions",
    data=json.dumps(body).encode("utf-8"),
    headers={'resource': os.environ["RESOURCE_KEY"], 'service-api-key': os.environ["SERVICE_API_KEY"], 'Content-Type': "application/json"}, method="POST")
try:
    with urlopen(request) as response:
        print(response.status, json.load(response))
except HTTPError as error:
    print(error.code, json.load(error))

{
  "success": true
}

{
  "error": "external_purchase_error",
  "error_description": "Current subscription is Higher-Tier Price"
}

Change an existing external membership

PUT /api/v1/integrations/users/{user_id}/external/subscriptions

Change trial, renewal and/or stored end-date fields on the first existing external membership for the target user and selected Pricing. This call does not create a membership, transaction or purchase, and does not change a provider’s renewal agreement.

Before you call

Use the shared service-account context and the grant for this exact action.

This controller requires an active resolved account user and valid resource; an attached resource relationship, when present, must not be locked or suspended. The target user must exist and have a relationship with this resource. Target activation/lock/suspension is not checked by the target lookup.

Select a Pricing already linked to this user by an is_external membership. A nonempty subscription.id takes precedence over source_id. It must be a nonzero JSON integer selecting a Pricing with a Plan in this resource; a string ID is rejected. Otherwise use a complete mapped subscription.source_id following Pricing lookup. No active/public Pricing condition is added.

For boolean changes, the handler compares the filtered input with the stored value, including its type. If they differ, it flips the stored flag instead of assigning the input directly. Stored types can therefore affect repeated requests. Inspect the resulting membership state before repeating a request.

Request

JSON body with Content-Type: application/json.

Omitted fields remain unchanged. Null/false present values still enter their property branches. Boolean filtering first lowercases and trims sanitized text: falsey values and the literal string "false" map to false; other nonempty text maps to true. Use actual JSON booleans. The create-only end_date key is not used here. A selector-only object still reaches save/event handling.

Result

Intended HTTP 200 result:

The selected membership is saved, timestamps/cache invalidation follow model hooks, and an external_user_subscription_update event is attempted with change information. Save return is not checked. Event handling follows the save; a later error does not prove the update was undone. No explicit action transaction, local transaction/purchase creation, membership replacement, provider renewal change or payment action is performed.

curl -X PUT "${WALLKIT_API_BASE}/api/v1/integrations/users/1001/external/subscriptions" \
  -H "resource: ${RESOURCE_KEY}" \
  -H "service-api-key: ${SERVICE_API_KEY}" \
  -H "Content-Type: application/json" \
  --data-raw '{"subscription": {"id": 3001, "is_autorenew": false, "subscription_end_date": "2026-11-01"}}'

const response = await fetch(`${process.env.WALLKIT_API_BASE}/api/v1/integrations/users/1001/external/subscriptions`, {
  method: "PUT",
  headers: {"resource": process.env.RESOURCE_KEY, "service-api-key": process.env.SERVICE_API_KEY, "Content-Type": "application/json"},
  body: JSON.stringify({"subscription": {"id": 3001, "is_autorenew": false, "subscription_end_date": "2026-11-01"}})
});
console.log(response.status, await response.json());

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

body = {'subscription': {'id': 3001, 'is_autorenew': False, 'subscription_end_date': '2026-11-01'}}
request = Request(os.environ["WALLKIT_API_BASE"] + "/api/v1/integrations/users/1001/external/subscriptions",
    data=json.dumps(body).encode("utf-8"),
    headers={'resource': os.environ["RESOURCE_KEY"], 'service-api-key': os.environ["SERVICE_API_KEY"], '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
}

{
  "error": "external_subscription_failed",
  "error_description": "Update external subscription has failed"
}

Apply configured external membership downgrade

DELETE /api/v1/integrations/users/{user_id}/external/subscriptions/{subscription_id}

Apply Wallkit’s configured downgrade handling to an existing external membership. The subscription_id path value is the Wallkit Pricing ID, not the membership relationship ID. This is not a provider refund or a guaranteed delete-only result.

Before you call

Use the shared service-account context and the grant for this exact action.

This controller requires an active resolved account user and valid resource; an attached resource relationship, when present, must not be locked or suspended. The target user must exist and have a relationship with this resource. Target activation/lock/suspension is not checked by the target lookup.

The Pricing must belong to this resource, and the target user must have an existing is_external membership for it. Use a Pricing ID retained from lookup or existing membership data. No end-date expiry condition is required by this route. Ask the integration owner which Pricing/resource fallback is configured before requesting this transition.

Request

Bodyless DELETE; no JSON selector is used.

Result

Intended HTTP 200 returns success:true only.

The configured Pricing downgrade is attempted first. If no replacement is recognized, the resource setting named downgrade_subscription_id is tried as the fallback. If neither replacement is recognized, the old membership is stored in history. The handler then attempts to delete the old membership; it does not use the next-Pricing branch for this route.

Replacement uses the membership helper and can change other memberships under single_subscription, record history, apply normal renewal defaults, stop sponsored gifts or clear multi-seat slots, invalidate caches and clear user content-view records when auto_clear_content_views is enabled. The replacement is not explicitly marked external, and its ID is not returned. Downgrade/sponsor/synchronization events may be attempted. Inner migration and handler exceptions are logged/swallowed, and a failed delete is logged. success:true therefore does not certify removal, replacement, exact resulting entitlement or notification delivery.

No explicit outer action transaction or provider money movement is performed. A partial transition is possible; repeated calls may find the original external membership missing or may repeat effects if it remains.

curl -X DELETE "${WALLKIT_API_BASE}/api/v1/integrations/users/1001/external/subscriptions/3001" \
  -H "resource: ${RESOURCE_KEY}" \
  -H "service-api-key: ${SERVICE_API_KEY}"

const response = await fetch(`${process.env.WALLKIT_API_BASE}/api/v1/integrations/users/1001/external/subscriptions/3001`, {
  method: "DELETE",
  headers: {"resource": process.env.RESOURCE_KEY, "service-api-key": process.env.SERVICE_API_KEY}
});
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/integrations/users/1001/external/subscriptions/3001",
    headers={'resource': os.environ["RESOURCE_KEY"], 'service-api-key': os.environ["SERVICE_API_KEY"]}, method="DELETE")
try:
    with urlopen(request) as response:
        print(response.status, json.load(response))
except HTTPError as error:
    print(error.code, json.load(error))

{
  "success": true
}

{
  "error": "external_subscription_failed",
  "error_description": "Downgrade external subscription has failed"
}

Record an external refund and handle linked memberships

PUT /api/v1/integrations/users/{user_id}/external/subscriptions/refund

Record a refund amount on an existing external transaction and invoke downgrade handling for qualifying linked memberships. The external system must handle money separately: this route makes no provider refund call and does not prove money returned. Even a partial recorded refund can trigger membership downgrade.

Before you call

Use the shared service-account context and the grant for this exact action.

This controller requires an active resolved account user and valid resource; an attached resource relationship, when present, must not be locked or suspended. The target user must exist and have a relationship with this resource. Target activation/lock/suspension is not checked by the target lookup.

Supply the external transaction ID for a stored is_external transaction matching this target user and resource. This is stricter than resource-only transaction lookup. Associated purchase relationships and an optional external catalog token can select memberships for downgrade; inspect them before recording.

Request

JSON body with Content-Type: application/json.

Omitting refund_amount fails; supplying 0 does not record zero refund. Null/present enters the filter branch. This is an overwrite, not an increment or cumulative-delta calculation. Supply the intended already-completed external amount; do not use negative or over-amount values merely because no guard is visible.

Result

Intended HTTP 200 returns success:true only.

The transaction amount_refunded is overwritten and saved; status is not changed to a refunded enum, and no provider refund record is created here. The transaction model updates timestamp/casts and may adjust fee fields under its normal save rules.

For each linked purchase whose relation_model is user_plan_relationships and relation_id is nonempty, the existing relationship must exist and its user_id must strictly match the target user. Its Pricing ID is then passed to the external membership downgrade helper, which selects a first external user/Pricing relationship; this does not guarantee deletion of the purchase’s exact relation_id. Inapplicable purchase links are skipped. A selected nonexternal/missing external membership can instead fail later; recording the refund amount comes first.

When external_subscription_source_id is present, its mapped Pricing is resolved in the resource, and a user/Pricing membership is looked up before external-only downgrade. This lookup itself does not require is_external; the following downgrade does. Missing optional membership is skipped, while invalid mapping or later failures can produce an error. The same membership can be reached more than once; no deduplication is promised.

Downgrade handling keeps the replacement/history/delete and swallowed-failure limits. Amount 500 does not limit membership changes to a partial entitlement adjustment. The outer action begins a transaction, commits before its final external refund event, and can enter nested membership transactions/events. Saves are not all checked; no atomicity, delivery or replay guarantee is established.

curl -X PUT "${WALLKIT_API_BASE}/api/v1/integrations/users/1001/external/subscriptions/refund" \
  -H "resource: ${RESOURCE_KEY}" \
  -H "service-api-key: ${SERVICE_API_KEY}" \
  -H "Content-Type: application/json" \
  --data-raw '{"transaction": {"id": "order-reader-1001", "refund_amount": 500}}'

const response = await fetch(`${process.env.WALLKIT_API_BASE}/api/v1/integrations/users/1001/external/subscriptions/refund`, {
  method: "PUT",
  headers: {"resource": process.env.RESOURCE_KEY, "service-api-key": process.env.SERVICE_API_KEY, "Content-Type": "application/json"},
  body: JSON.stringify({"transaction": {"id": "order-reader-1001", "refund_amount": 500}})
});
console.log(response.status, await response.json());

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

body = {'transaction': {'id': 'order-reader-1001', 'refund_amount': 500}}
request = Request(os.environ["WALLKIT_API_BASE"] + "/api/v1/integrations/users/1001/external/subscriptions/refund",
    data=json.dumps(body).encode("utf-8"),
    headers={'resource': os.environ["RESOURCE_KEY"], 'service-api-key': os.environ["SERVICE_API_KEY"], '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
}

{
  "error": "transaction_not_found",
  "error_description": "Transaction not found"
}