Topolo Docs Topolo Platform
Open workspace

Read Suite signup checkout

Read the sanitized checkout subscription using its protected session-bound handoff credential.

Read the sanitized checkout subscription using its protected session-bound handoff credential.

Action app_topolo_one.signup.checkout.get · POST /api/signup/checkout-status. Intended audience: public.

Catalog flags: readOnly=True, requiresConfirmation=False, destructive=False, agentAccess=auto. HTTP method and empty permission fields do not override the actual effects or authority below.

Authority and prerequisites

  • Declared authorization mode=public, requiredPermission=empty; actual source identity/resource checks below remain mandatory.
  • Discover the actual identifier and current intended state within existing authority. Examples grant no access and are not executable probes.

Identifiers

  • Use the exact original checkout session and matching unexpired protected handoff from that origin. Never substitute another session ID or take a null result as a failed payment.

Input

  • sessionId: type="string"; pattern="^cs_[A-Za-z0-9_]{1,190}$". Required.
  • handoffToken: type="string"; pattern="^\d{1,10}\.[a-f0-9]{64}$". Required.

The exact native input/output schemas are retained in the hidden paired layer for this version. Top-level undeclared fields are rejected. Nested open records and semantic prerequisites still need source checks.

Effects and important boundaries

  • Reads sanitized subscription state after verifying the exact checkout handoff. Takes no money and exposes no buyer email or provider credential.
  • These are the marketing signup actions, distinct from the older app_topolo_one.checkout.create/quote guides. Do not overwrite or rename those existing records.
  • Catalog-public transport is protected by business/human prerequisites. The checkout handoff is a secret origin-and-session-bound HMAC credential, valid only until its expiry (maximum 24 hours), not an unrestricted user/org grant.
  • The examples contain unusable synthetic tokens and session IDs. They demonstrate schema shape only; no token was generated, no buyer was queried, and no account/trial/checkout/charge/grant was created.
  • Protect checkout handoff and owner login credentials; never put real values in general documentation, logs or a shareable receipt.
  • This read uses POST with a strict JSON sessionId/handoffToken body, then delegates to the internal sanitized GET lookup with a synthesized protected cookie. HTTP method alone does not imply a write or dispense with credential checks.
  • Returns subscription=null until a subscription is visible. Present subscriptions include sanitized status/quantity/period/quote fields and may contain external user/org identifiers; they do not expose the buyer email or raw provider secret.
  • Before Suite provisioning, require active or unexpired trialing status and valid human-seat capacity. Although past_due passes the provision handler’s first check, its later Suite-specific guard refuses that state with 422 INVALID_HUMAN_SEAT_SUBSCRIPTION.

Refusals, failures and recovery

  • 403 CHECKOUT_SIGN_IN_REQUIRED: Use the protected handoffToken returned by this checkout on the same environment and site. A checkout URL or session ID alone is not buyer authority. Start a new checkout if the credential expired.
  • 400 VALIDATION_ERROR: Correct only the schema-invalid input. Keep the original protected token and session ID together.
  • 502 LOOKUP_ERROR: Retry this read with the same session and protected handoff after the temporary lookup failure. Do not create another checkout.

This read does not change a subscription or charge money.

Verification

  • Wait for an active or unexpired trialing subscription before provisioning. A null subscription means the webhook has not completed.
  • Retain actual request/receipt identifiers securely, preserve UNKNOWN effects and reconcile before any retry.

Run a reviewed request

Discover the current action and its resource requirements before running it. Save the approved input as reviewed-input.json; replace synthetic examples with values obtained through the intended authorized workflow. If discovery requires a resource binding, provide its published type and resolved ID separately on both plan and call. Stop if validation fails or the plan is not executable.

topolo actions get app_topolo_one.signup.checkout.get --json
topolo actions validate app_topolo_one.signup.checkout.get --data @reviewed-input.json --json
topolo actions plan app_topolo_one.signup.checkout.get --data @reviewed-input.json --json
topolo actions call app_topolo_one.signup.checkout.get --data @reviewed-input.json --json

For local CLI/MCP secret outputs, pass the protected topolo-secret: reference unchanged; do not extract the underlying checkout or login credential into a file or log.

Worked examples

All examples are synthetic and unrun. They cannot authorize access, create human consent, prove media/provider success or establish financial/customer state. Placeholder tokens are unusable. No contact, payment, notification, provisioning or business read was executed.

No subscription visible yet

SOURCE-AUTHORED SYNTHETIC, UNRUN. Output assessment: PASS_STRUCTURAL_ONLY_UNRUN.

Input:

{
  "sessionId": "cs_example",
  "handoffToken": "1700000000.aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}

Output illustration or error excerpt:

{
  "success": true,
  "checkoutSessionId": "cs_example",
  "subscription": null
}

200 hypothetical null subscription is incomplete asynchronous state, not completed signup.

Refusal or failure

SOURCE-AUTHORED SYNTHETIC, UNRUN. Source-derived error-code excerpt only; messages/envelope can differ by layer or locale. Not a captured response. Output assessment: ERROR_EXCERPT_NOT_SUCCESS_SCHEMA.

Input:

{
  "sessionId": "cs_example",
  "handoffToken": "1700000000.aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}

Output illustration or error excerpt:

{
  "error": "CHECKOUT_SIGN_IN_REQUIRED"
}

Wrong, expired or mismatched handoff cannot read this subscription.

Invalid input: stop at schema validation

SOURCE-AUTHORED SYNTHETIC, UNRUN. null is a no-response sentinel, not returned JSON null. Output assessment: NOT_APPLICABLE_NO_REQUEST.

Input:

{
  "handoffToken": "1700000000.aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}

Output illustration or error excerpt:

null

Intentionally invalid input; no request was issued and no HTTP response/status is asserted.

Boundary: provider lookup failure

SOURCE-AUTHORED SYNTHETIC, UNRUN. Output assessment: ERROR_EXCERPT_NOT_SUCCESS_SCHEMA.

Input:

{
  "sessionId": "cs_example",
  "handoffToken": "1700000000.aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}

Output illustration or error excerpt:

{
  "code": "LOOKUP_ERROR"
}

502 remains a dependency failure, not a successful null subscription.

Source and verification limits

Reviewed against cb18601dad6735f8140a4c81e9650d9fc3599f9a at apps/marketing/worker/signup-action-routes.js and the published action schema on 2026-10-20. Examples are synthetic and unrun. Source review and schema validation do not prove current deployed behavior, provider completion or business delivery. Response excerpts are labelled where incomplete.

Change log

  • 2026-10-20: Prepared the action guide with paired agent schemas, permission and effect boundaries, worked examples, verification and recovery instructions. Independently checked the pinned source; publication and runtime verification remain separate.