Topolo Docs Topolo Platform
Open workspace

Start Essential signup checkout

Start one Essential checkout per person with the accepted usage rate card; checkout presents the current terms. First-party apps and agent access are included.

Start one Essential checkout per person with the accepted usage rate card; checkout presents the current terms. First-party apps and agent access are included.

Action app_topolo_one.signup.checkout.create · POST /api/signup/checkout. Intended audience: public.

Catalog flags: readOnly=False, requiresConfirmation=True, destructive=False, agentAccess=confirm. 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

  • Generate one attemptId for the actual confirmed signup. Discover current central offer/card first; do not use the illustrative accepted-active-version as an existence or active-card proof.

Input

  • attemptId: type="string"; pattern="^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$". Required.
  • planId: type="string"; const="topoloone". Required.
  • billing: type="string"; enum=["monthly", "annual"]. Required.
  • email: type="string"; pattern="^(?!\.)(?!.\.\.)([A-Za-z0-9_'+\-\.])[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$". Required.
  • name: type="string"; minLength=1; maxLength=256. Required.
  • company: type="string"; minLength=1; maxLength=256. Required.
  • workspaceSlug: type="string"; pattern="^a-z0-9$"; minLength=3; maxLength=48. Required.
  • seatCount: type="integer"; minimum=1; maximum=250. Required.
  • usageRateCardAccepted: type="boolean"; const=true. Required.
  • usageRateCardVersion: type="string"; minLength=1. 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

  • Records an immutable accepted quote and request digests before provider dispatch. Repeating the same attemptId and unchanged input within 18 hours recovers the same provider checkout.
  • Creates a Stripe-hosted Suite subscription checkout at the centrally computed price per person.
  • Records acceptance of the current usage rate card. Completing checkout starts the card-required trial; charges follow the accepted offer.
  • Returns a protected handoffToken for status/provisioning. Never disclose the underlying token or service credentials.
  • 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.
  • Requires explicit approval of the real buyer, current offer, monthly/annual billing, human seat count 1..250 and accepted current usageRateCardVersion. planId is topoloone; this action fixes packageId=suite and source=signup-action internally.
  • Persists an immutable accepted quote/request digest before provider dispatch. Retain one UUID v4 attemptId and unchanged input. Identical retries within 18 hours reuse the provider idempotency contract; changed details or expired attempts require reconciliation.
  • Creates a Stripe-hosted subscription checkout. Completing it can start a card-required trial and later charges under the accepted offer. A returned URL is not a paid subscription or completed signup.
  • The title calls the product Essential while storage/package terminology includes Suite. Use the exact current central offer and returned plan, not legacy static prices or inferred equivalence.

Refusals, failures and recovery

  • 400 VALIDATION_ERROR: Use the exact Suite signup input schema. Per-app selection, billing-owner IDs and supplied prices are not accepted.
  • 503 USAGE_PRICING_NOT_CONFIGURED: Wait for published active rates. Draft rates cannot authorize checkout.
  • 400 USAGE_RATE_CONSENT_REQUIRED: Obtain acceptance of the actual terms and usage rates before confirming this action.
  • 409 USAGE_RATE_CARD_CHANGED: Read the current offer and obtain acceptance of its new rate-card version before a new checkout.
  • 503 STRIPE_NOT_CONFIGURED: Wait for verified provider configuration. Do not switch environments or supply another Stripe key.
  • 409 CHECKOUT_ATTEMPT_CONFLICT: Retry only the original unchanged input and attemptId. Changed details or a changed provider payload require reconciliation before another attempt.
  • 409 CHECKOUT_ATTEMPT_EXPIRED: The 18-hour recovery window ended. Reconcile the original attempt through support before creating another checkout; do not generate a new attemptId automatically.
  • 500 STRIPE_ERROR: Retain the attemptId, unchanged input, TopoloOne request ID and returned dependency identifiers. Creation may have reached the provider. Retry that identical attempt within 18 hours to recover it; never replace the attemptId after an ambiguous response.

Generate one random UUID v4 before the first request. After an ambiguous error, retry only that same attemptId and unchanged input within 18 hours. Expired or conflicting attempts require reconciliation, not a new automatic checkout. After completion, read and provision the original session.

Verification

  • Compare the returned plan price and number of people to the accepted offer.
  • After completing hosted checkout, use the unchanged protected token and session ID with the checkout read.
  • 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.create --json
topolo actions validate app_topolo_one.signup.checkout.create --data @reviewed-input.json --json
topolo actions plan app_topolo_one.signup.checkout.create --data @reviewed-input.json --confirm --json
topolo actions call app_topolo_one.signup.checkout.create --data @reviewed-input.json --confirm --json

--confirm must represent approval of the actual request and its effects. The examples do not supply that approval.

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.

Accepted checkout response excerpt

SOURCE-AUTHORED SYNTHETIC, UNRUN. Partial excerpt; not a complete response. Output assessment: PARTIAL_EXCERPT_NOT_COMPLETE_SCHEMA.

Input:

{
  "attemptId": "68f68ec8-1d36-41de-933e-d834126af9b6",
  "planId": "topoloone",
  "billing": "annual",
  "email": "owner@example.test",
  "name": "Owner",
  "company": "Example",
  "workspaceSlug": "example-team",
  "seatCount": 1,
  "usageRateCardAccepted": true,
  "usageRateCardVersion": "accepted-active-version"
}

Output illustration or error excerpt:

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

Partial hypothetical response; URL and computed plan/price omitted. The synthetic handoff is unusable and expired, not a live successful checkout.

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:

{
  "attemptId": "68f68ec8-1d36-41de-933e-d834126af9b6",
  "planId": "topoloone",
  "billing": "annual",
  "email": "owner@example.test",
  "name": "Owner",
  "company": "Example",
  "workspaceSlug": "example-team",
  "seatCount": 1,
  "usageRateCardAccepted": true,
  "usageRateCardVersion": "accepted-active-version"
}

Output illustration or error excerpt:

{
  "error": "USAGE_PRICING_NOT_CONFIGURED"
}

No active configured usage offer means stop before provider checkout; no bypass or financial write is authorized.

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:

{
  "planId": "topoloone",
  "billing": "annual",
  "email": "owner@example.test",
  "name": "Owner",
  "company": "Example",
  "workspaceSlug": "example-team",
  "seatCount": 1,
  "usageRateCardAccepted": true,
  "usageRateCardVersion": "accepted-active-version"
}

Output illustration or error excerpt:

null

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

Boundary: conflicting attempt identity

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

Input:

{
  "attemptId": "68f68ec8-1d36-41de-933e-d834126af9b6",
  "planId": "topoloone",
  "billing": "annual",
  "email": "owner@example.test",
  "name": "Owner",
  "company": "Example",
  "workspaceSlug": "example-team",
  "seatCount": 1,
  "usageRateCardAccepted": true,
  "usageRateCardVersion": "accepted-active-version"
}

Output illustration or error excerpt:

{
  "code": "CHECKOUT_ATTEMPT_CONFLICT"
}

409 when the same attemptId has changed request/quote payload. Reconcile the original; do not create a new automatic checkout.

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.