Skip to content
threada Docs

Commercial Marketplaces

This guide covers the shared Threada setup path for commercial marketplace procurement across AWS Marketplace, Microsoft commercial marketplace, Google Cloud Marketplace, and Oracle Cloud Marketplace.

Current Status

Threada has the public BFF procurement callback and provider-neutral billing runtime needed for commercial marketplace entitlement lifecycle events. The public callback is POST /api/v1/commercial-marketplaces/{provider}/procurement, and the billing boundary is BillingService.RecordMarketplaceProcurementEvent, which records signed adapter-supplied buyer, entitlement, product, plan, status, subscription metadata, and billing audit events for active, suspended, and canceled marketplace states.

Private launch-control packages now exist for each commercial marketplace:

  • packages/aws-marketplace-app
  • packages/microsoft-commercial-marketplace-app
  • packages/google-cloud-marketplace-app
  • packages/oracle-cloud-marketplace-app

These packages generate the technical configuration, marketplace listing metadata, required asset checklist, readiness report, and reviewer smoke test for the provider submission. They are not provider approval evidence.

Public availability remains blocked until the real provider seller, publisher, or producer account exists, the listing is configured in that provider portal, the provider fulfillment adapter points to the production procurement callback, and sanitized review evidence is captured.

Runtime Contract

Provider-specific fulfillment adapters terminate at the public BFF callback: /api/v1/commercial-marketplaces/{provider}/procurement, where {provider} is aws, microsoft, google_cloud, or oracle. The callback requires:

  • X-Threada-Marketplace-Tenant: Threada tenant ID from the reviewer/customer entitlement mapping.
  • X-Threada-Marketplace-Timestamp: Unix epoch seconds within five minutes.
  • X-Threada-Marketplace-Signature: v1=<hex hmac-sha256>.
  • HMAC base string: v1:{provider}:{tenant}:{timestamp}:{raw_body}.
  • Provider signing secret from Secret Manager: AWS_MARKETPLACE_PROCUREMENT_SIGNING_SECRET, MICROSOFT_MARKETPLACE_PROCUREMENT_SIGNING_SECRET, GOOGLE_CLOUD_MARKETPLACE_PROCUREMENT_SIGNING_SECRET, or ORACLE_CLOUD_MARKETPLACE_PROCUREMENT_SIGNING_SECRET.

The Threada tenant is not accepted from the JSON body. It must be resolved by the provider-side fulfillment adapter from the marketplace buyer/entitlement mapping, placed in X-Threada-Marketplace-Tenant, and covered by the HMAC signature. After callback verification, the BFF normalizes provider payloads and calls BillingService.RecordMarketplaceProcurementEvent with:

  • Threada tenant ID.
  • Marketplace buyer ID.
  • Marketplace entitlement ID.
  • Marketplace product ID.
  • Paid plan ID.
  • Lifecycle status: active, suspended, or canceled.
  • Source event ID.
  • Event timestamp.

Billing rejects incompatible bindings, avoids silently provisioning a tenant for suspended or canceled unmapped events, and stores an audit event for every accepted provider transition.

Provider payload adapters are strict and reject unknown fields. Required provider fields are:

  • AWS: customerIdentifier, productCode, plan, status, sourceEventId, plus customerAwsAccountId, entitlementId, or licenseArn when the provider response supplies them.
  • Microsoft: subscriptionId, offerId, planId, status, operationId, and optional purchaserTenantId.
  • Google Cloud: accountId, entitlementId, productId, plan, state, and eventId.
  • Oracle: customerId, listingId, acquisitionId, plan, status, and sourceEventId.

Timestamp fields are optional RFC3339 strings (eventTime for AWS, Microsoft, and Oracle; updateTime for Google Cloud). If omitted, Billing uses its receive time.

Reviewer Setup

Use reviewer-safe marketplace accounts, buyer identities, and Threada tenants. Do not use customer data, raw provider payloads, secrets, cookies, invoices, or private tenant content in review evidence.

For each provider review:

  • Configure the marketplace product, listing, and plan in the provider portal.
  • Configure the provider fulfillment adapter to post to the provider-specific Threada procurement callback.
  • Store provider callback signing secrets in Secret Manager.
  • Map the reviewer buyer and entitlement to a reviewer-safe Threada tenant.
  • Exercise active and canceled or suspended lifecycle states.
  • Capture sanitized evidence refs for the package readiness command.

Provider Packages

Each package has a provider-specific build command:

  • AWS Marketplace: pnpm --filter @threada/aws-marketplace-app aws:package
  • Microsoft commercial marketplace: pnpm --filter @threada/microsoft-commercial-marketplace-app microsoft:package
  • Google Cloud Marketplace: pnpm --filter @threada/google-cloud-marketplace-app google-cloud:package
  • Oracle Cloud Marketplace: pnpm --filter @threada/oracle-cloud-marketplace-app oracle:package

Run the matching *:validate:submission command only after the real provider configuration and evidence refs exist. The command should fail closed while any provider account, listing, Secret Manager procurement signing-secret reference, runtime binding, or reviewer smoke evidence is missing.

AWS Marketplace

Use the AWS package for the SaaS product or private offer path. The package expects the seller account ID, product ID, listing ID, plan ID, production fulfillment URL, Secret Manager procurement signing-secret ref, and sanitized evidence for the seller, product, entitlement, reviewer smoke, and approval gates.

Do not claim AWS Marketplace availability, entitlement sync, metering, private offers, or buyer onboarding until the AWS listing and verified fulfillment adapter evidence exist.

Microsoft Commercial Marketplace

Use the Microsoft package for the Partner Center SaaS offer path. The package expects the publisher ID, offer/listing ID, plan ID, production landing or fulfillment URL, Secret Manager procurement signing-secret ref, and sanitized evidence for the publisher, offer, entitlement lifecycle, reviewer smoke, certification, and approval gates.

Do not claim AppSource or Azure Marketplace availability, private plans, subscription lifecycle support, or commercial certification until Microsoft review passes.

Google Cloud Marketplace

Use the Google Cloud package for the Marketplace SaaS listing path. The package expects the producer project ID, product ID, listing ID, plan ID, production procurement or fulfillment URL, Secret Manager procurement signing-secret ref, and sanitized evidence for the partner account, product, entitlement lifecycle, reviewer smoke, and approval gates.

Do not claim Google Cloud Marketplace availability, entitlement sync, metering, or buyer onboarding until the listing, adapter, and review evidence exist.

Oracle Cloud Marketplace

Use the Oracle package for the Marketplace service, application, or acquisition path. The package expects the publisher ID, listing ID, product ID, plan ID, production acquisition or fulfillment URL, Secret Manager procurement signing-secret ref, and sanitized evidence for the partner portal, listing, handoff or entitlement lifecycle, reviewer smoke, and approval gates.

Do not claim Oracle Cloud Marketplace availability, OPN approval, buyer procurement, or automated provisioning until partner and listing review evidence exist.

Data Handling

Commercial marketplace setup reads procurement entitlement metadata from the provider and writes subscription state and audit history in Threada. It does not ingest customer content, cloud resources, invoices, historical provider activity, or broad marketplace account data.