Registration Page

The main stack outputs a RegistrationUrl — a raw API Gateway endpoint. When a buyer clicks Set up your account in AWS Marketplace, Marketplace redirects them to the product’s Fulfillment URL with an x-amzn-marketplace-token (POSTed as form data). The register Lambda behind RegistrationUrl calls ResolveCustomer with that token and persists CustomerAWSAccountId + LicenseArn + ProductCode (+ any allowlisted extra fields) to the subscribers table.

That backend is not a finished onboarding experience. The product’s Fulfillment URL should point at the branded front-end page, not at the raw RegistrationUrl — the Marketplace redirect must land the buyer’s browser on a page that renders. Pointing the Fulfillment URL straight at RegistrationUrl gives the buyer no page (and no branding or extra-field capture) and is only a bare-bones fallback for an initial smoke test. Most sellers want a branded, buyer-facing registration page — this is what the AWS Serverless SaaS Integration reference architecture and the Marketplace seller onboarding lab provide. Do not let a seller believe onboarding is “done” once the backend deploys.

Recommended pattern (branded page)

A static site that is itself the Fulfillment URL target and sits in front of the RegistrationUrl:

• S3 + CloudFront host the page (optionally a custom domain + an ACM certificate so the Fulfillment URL is the seller’s own branded domain). The AMMP Fulfillment URL points here.
• The page receives the Marketplace redirect (buyer’s browser + token), renders the seller’s branding/marketing, and captures additional buyer fields (e.g. contact name, email, company, use-case).
• On submit it forwards the token unchanged plus the captured fields (as allowlisted form keys) to RegistrationUrl (the backend). The token is short-lived (~4h) and reusable until expiry.
• Secure the public page (same protections the backend RegistrationUrl already gets):
  • Attach a CloudFront response-headers policy setting Content-Security-Policy, Strict-Transport-Security (HSTS), X-Frame-Options, and X-Content-Type-Options so the buyer-facing page carries the same security headers the register Lambda returns.
  • Front the CloudFront distribution with AWS WAF (a rate-based rule + the common-exploit managed rule set) for defense in depth on this public, unauthenticated page.

The page’s markup/branding is seller-owned (like usage-write logic — out of scope of the generated backend), but the skill can scaffold the S3 + CloudFront (+ optional custom domain, response-headers policy, and WAF association) and wire the form contract on request. Ask the seller whether they want the branded-page scaffold or will host their own.

Capture “Know Your Buyer” (KYB) fields from the start

The register Lambda (in-region) persists ONLY the fields named in ALLOWED_REGISTRATION_FIELDS (comma-separated, each length-bounded, up to a max count; the token is never stored) — and it writes them to the in-region customer-profile table (PK licenseArn + SK customerAWSAccountId), NOT the subscribers table (which is kept PII-free and lives in us-east-1). Because the profile table is schemaless, no table change is needed to add a buyer attribute — you only need (1) the field on the onboarding form and (2) the field name in the allowlist; add a GSI on the profile table only if you want to look profiles up by that field.

At initial integration, propose capturing the buyer fields the AWS Marketplace Know Your Buyer (KYB) initiative plans to collect — typically buyer contact name, email, company/organization, and use-case — so they are written into the customer-profile table from day one. Doing this up front avoids a later backfill/migration when KYB fields become required.

This describes a NEW skill-generated integration. For an EXISTING seller stack the skill ADAPTS instead: the seller may already store registration data in their own shape, and if their subscribers table already holds buyer PII, moving it to a per-Region profile table is a data migration + code cutover — not a drop-in. See references/existing-sellers.md → “Adding a new capability to an EXISTING stack”.

Guidance:

• Set ALLOWED_REGISTRATION_FIELDS to the seller’s chosen KYB + custom fields (e.g. contact_name,contact_email,company,use_case).
• Keep the fields OPTIONAL and seller-confirmed — do not invent PII fields the seller did not ask for; whether a KYB field is mandatory is an AWS Marketplace program decision, not this skill’s.
• Buyer PII stays IN-REGION (in the customer-profile table) and OUT of logs (identifiers are masked on output); the token is never persisted; PII is never written to the us-east-1 subscribers table.