List campaign redemptions — Campaigns

Reads the campaign redemption ledger and sums stored value and commissionAccrued. It does not redeem a code, charge a payment, pay commission or send a notification. A missing campaign returns HTTP 404 campaign_not_found.

Retained immutable local-fixture guide, refreshed against current production catalog metadata. No examples were rerun by this author; no production action was invoked.

List campaign redemptions

Outcome

After authentication and the canonical workspace grant succeed, a first workspace request may initialize the app-local identity mirror and recipient setting before the application permission check. These reads do not modify campaign-domain records or execute notifications.

Before you start

Verify the intended environment, authenticated identity and organization before discovery.
Discover the published redemptions:read application permission and inspect the credential-scoped action contract.
Discover and bind the granted canonical Campaigns workspace separately from the action input.
Fixture identifiers and simulated responses confer no live access. Replace identifiers through granted resource discovery.

Discover the target

topolo whoami --json
topolo workspaces list topolo-campaigns --json
topolo actions get app_topolo_campaigns.redemptions.list --json

Read app_topolo_campaigns.campaigns.list in this same authorized context and select campaigns[].id. Do not derive ids from display names.
Inspect app_topolo_campaigns.campaigns.get in the same credential and resource context before reading it.
Inspect app_topolo_campaigns.campaigns.dashboard.get in the same credential and resource context before reading it.

Request

GET /api/campaigns/{id}/redemptions

Input fields

Field	Required	Meaning and constraints
`id`	Yes	Campaign identifier returned by campaigns.list in the same authorized organization and workspace. Type: string. minLength: 1

Worked examples

populated resource · HTTP 200

Input · payload.json:

{
  "id": "campaign_docs_fixture"
}

CLI:

topolo actions validate app_topolo_campaigns.redemptions.list --data @payload.json --json
topolo actions plan app_topolo_campaigns.redemptions.list --resource-type workspace --resource-id "$CAMPAIGNS_WORKSPACE_ID" --data @payload.json --json
topolo actions call app_topolo_campaigns.redemptions.list --resource-type workspace --resource-id "$CAMPAIGNS_WORKSPACE_ID" --data @payload.json --json

MCP tool and arguments:

{
  "tool": "topolo_read_action",
  "arguments": {
    "actionId": "app_topolo_campaigns.redemptions.list",
    "input": {
      "id": "campaign_docs_fixture"
    },
    "resourceType": "workspace",
    "resourceId": "<identifier returned by granted resource discovery>"
  }
}

Captured local response · HTTP 200:

{
  "redemptions": [
    {
      "id": "redemption_docs_fixture",
      "codeId": "code_docs_fixture",
      "campaignId": "campaign_docs_fixture",
      "redeemedBy": null,
      "value": 20,
      "commissionAccrued": 2,
      "source": "manual",
      "redeemedAt": "2026-10-07T00:00:00.000Z"
    }
  ],
  "totalValue": 20,
  "totalCommission": 2
}

populated resource: HTTP 200.

empty workspace · HTTP 404

Input · payload.json:

{
  "id": "campaign_docs_fixture"
}

CLI:

topolo actions validate app_topolo_campaigns.redemptions.list --data @payload.json --json
topolo actions plan app_topolo_campaigns.redemptions.list --resource-type workspace --resource-id "$CAMPAIGNS_WORKSPACE_ID" --data @payload.json --json

MCP tool and arguments:

{
  "tool": "topolo_prepare_action",
  "arguments": {
    "actionId": "app_topolo_campaigns.redemptions.list",
    "input": {
      "id": "campaign_docs_fixture"
    },
    "resourceType": "workspace",
    "resourceId": "<identifier returned by granted resource discovery>"
  }
}

Captured local response · HTTP 404:

{
  "error": "campaign_not_found"
}

empty workspace: HTTP 404; SDK code http_error.

campaign absent · HTTP 404

Input · payload.json:

{
  "id": "campaign_unknown_fixture"
}

CLI:

topolo actions validate app_topolo_campaigns.redemptions.list --data @payload.json --json
topolo actions plan app_topolo_campaigns.redemptions.list --resource-type workspace --resource-id "$CAMPAIGNS_WORKSPACE_ID" --data @payload.json --json

MCP tool and arguments:

{
  "tool": "topolo_prepare_action",
  "arguments": {
    "actionId": "app_topolo_campaigns.redemptions.list",
    "input": {
      "id": "campaign_unknown_fixture"
    },
    "resourceType": "workspace",
    "resourceId": "<identifier returned by granted resource discovery>"
  }
}

Captured local response · HTTP 404:

{
  "error": "campaign_not_found"
}

campaign absent: HTTP 404; SDK code http_error.

workspace grant denied · HTTP 403

Input · payload.json:

{
  "id": "campaign_docs_fixture"
}

CLI:

topolo actions validate app_topolo_campaigns.redemptions.list --data @payload.json --json
topolo actions plan app_topolo_campaigns.redemptions.list --resource-type workspace --resource-id "$CAMPAIGNS_WORKSPACE_ID" --data @payload.json --json

MCP tool and arguments:

{
  "tool": "topolo_prepare_action",
  "arguments": {
    "actionId": "app_topolo_campaigns.redemptions.list",
    "input": {
      "id": "campaign_docs_fixture"
    },
    "resourceType": "workspace",
    "resourceId": "<identifier returned by granted resource discovery>"
  }
}

Captured local response · HTTP 403:

{
  "error": "workspace_forbidden"
}

workspace grant denied: HTTP 403; SDK code permission_denied.

permission denied · HTTP 403

Input · payload.json:

{
  "id": "campaign_docs_fixture"
}

CLI:

topolo actions validate app_topolo_campaigns.redemptions.list --data @payload.json --json
topolo actions plan app_topolo_campaigns.redemptions.list --resource-type workspace --resource-id "$CAMPAIGNS_WORKSPACE_ID" --data @payload.json --json

MCP tool and arguments:

{
  "tool": "topolo_prepare_action",
  "arguments": {
    "actionId": "app_topolo_campaigns.redemptions.list",
    "input": {
      "id": "campaign_docs_fixture"
    },
    "resourceType": "workspace",
    "resourceId": "<identifier returned by granted resource discovery>"
  }
}

Captured local response · HTTP 403:

{
  "error": "forbidden"
}

permission denied: HTTP 403; SDK code permission_denied.

authentication missing · HTTP 401

Input · payload.json:

{
  "id": "campaign_docs_fixture"
}

CLI:

topolo actions validate app_topolo_campaigns.redemptions.list --data @payload.json --json
topolo actions plan app_topolo_campaigns.redemptions.list --resource-type workspace --resource-id "$CAMPAIGNS_WORKSPACE_ID" --data @payload.json --json

MCP tool and arguments:

{
  "tool": "topolo_prepare_action",
  "arguments": {
    "actionId": "app_topolo_campaigns.redemptions.list",
    "input": {
      "id": "campaign_docs_fixture"
    },
    "resourceType": "workspace",
    "resourceId": "<identifier returned by granted resource discovery>"
  }
}

Captured local response · HTTP 401:

{
  "error": "Authentication required"
}

authentication missing: HTTP 401; SDK code auth_error.

Verify the result

Retain redemptions[].id, codeId and campaignId; compare totalValue and totalCommission to the sums of the returned rows. Source describes recorded attribution and is not a provider settlement receipt.

Errors and recovery

http_error (HTTP 404): For HTTP 404 campaign_not_found, repeat campaigns.list and campaigns.get in the same authorized workspace. Do not guess another identifier. Preserve the actual response and request id.
permission_denied (HTTP 403): Preserve the refusal. Verify the exact application permission and canonical workspace grant, or the organization boundary for export. Do not widen context or retry with a different resource to evade a denial.
auth_error (HTTP 401): Authenticate again in the intended environment and pinned organization, then repeat identity and resource discovery.

Authentication, input validation or resource middleware can refuse a request before these handlers. Preserve the actual refusal and request id.

Recovery boundary

These reads do not change campaign-domain records and require no domain rollback. A permission or privacy refusal is authoritative; preserve its context and request id.

Get campaign — Campaigns: Reads one non-deleted campaign in the bound organization and workspace. An absent or differently scoped campaign returns HTTP 404 campaign_not_found.
Get campaign dashboard — Campaigns: Reads stored batch, code, placement and redemption counts plus counts for each journey event type. Resource identity is the request id; the dashboard response contains counts. Stored events do not establish a live provider outcome.

Evidence

Actual Campaigns handleRequest, permission checks, store queries and replayed SQLite migrations. Credential verification and canonical workspace grants are simulated at the Auth package boundary; egress is sealed. No deployed/provider outcome, live redemption, outbound communication or live access is demonstrated.

Current field meanings and contract

Field	Required	Meaning and validation
`id`	Yes	Campaign identifier from campaigns[].id; scoped to the selected organization/workspace. It is not a batch/code/placement id. string; minLength=1

Exact schemas and provenance

Input schema:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false
}

Output schema:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "redemptions": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "codeId": {
            "type": "string"
          },
          "campaignId": {
            "type": "string"
          },
          "redeemedBy": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "value": {
            "type": "number"
          },
          "commissionAccrued": {
            "type": "number"
          },
          "source": {
            "type": "string"
          },
          "redeemedAt": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "codeId",
          "campaignId",
          "redeemedBy",
          "value",
          "commissionAccrued",
          "source",
          "redeemedAt"
        ],
        "additionalProperties": false
      }
    },
    "totalValue": {
      "type": "number"
    },
    "totalCommission": {
      "type": "number"
    }
  },
  "required": [
    "redemptions",
    "totalValue",
    "totalCommission"
  ],
  "additionalProperties": false
}

Reviewed immutable source: TopoloCampaigns@cacbb8b12b4e19a662cf82d03a927aef3c3a35e8, docs/action-read-records.json. Fresh production catalog was read on 2026-10-20. Its publication metadata is not proof that this source is loaded. Output examples are not widened or rewritten to force schema success; the accompanying validation record classifies exact success, refusal, no-body and structural-schema limits.

app_topolo_campaigns.campaigns.get: Read one campaign with its offer, codes, status and redemption totals.
app_topolo_campaigns.campaigns.dashboard.get: Read a campaign's dashboard: codes issued, redemptions and their total value.

Local input rejection example

This deliberately invalid input belongs to a pure schema check; it is never a planned or executed request. The closed action input schema must reject the extra field. It has no HTTP status or server response.

{
  "id": "campaign_docs_fixture",
  "__unsupported_field": true
}

The hidden companion labels this as ILLUSTRATIVE_LOCAL_SCHEMA_CHECK; its validation representation is not an action output.

Published output validation limits

Current published output qualification: the output schema rejects the empty-object, partial-success-marker, partial-data-object and refusal-body probes. A schema-valid success body still does not establish execution, live permission, selected context or a provider outcome.

These observations come from pure checks of the exact published schema; they are not server responses or production captures.

List campaign redemptions — Campaigns

List campaign redemptions

Outcome

Before you start

Discover the target

Request

Input fields

Worked examples

populated resource · HTTP 200

empty workspace · HTTP 404

campaign absent · HTTP 404

workspace grant denied · HTTP 403

permission denied · HTTP 403

authentication missing · HTTP 401

Verify the result

Errors and recovery

Recovery boundary

Related actions

Evidence

Current field meanings and contract

Exact schemas and provenance

Related actions

Local input rejection example

Published output validation limits