Marketplace Listing Sync¶

Plan Tier: Starter (available on all paid plans) Trigger: On AWS connect + every six hours Backend: AWS Marketplace Catalog API (ListEntities) over a cross-account IAM role

Overview¶

When you connect an AWS account, Vellocity doesn't make you re-enter your listings. It auto-discovers the AWS Marketplace listings that account actually owns and imports their metadata, so the first thing you see is your products — not an empty page or seeded demo data.

Discovery runs through the official AWS Marketplace Catalog API. Vellocity assumes a scoped, cross-account IAM role on your connection and calls the ListEntities operation across the supported entity types. It reads listing metadata; it does not bypass AWS, and it does not scrape your public listing pages.

How discovery works¶

Trigger points¶

Trigger	Mechanism
You connect an AWS account	`ConnectionController` dispatches `SyncListingsJob` for that connection (queued, background)
Ongoing refresh	`SyncAllListingsJob` runs every six hours (scheduled task `sync-marketplace-listings`), fanning out a `SyncListingsJob` per connection

Cross-account access¶

Vellocity reads your catalog through a cross-account IAM role rather than long-lived keys:

Your cloud connection stores an iam_role_arn and an external_id.
The sync performs an STS AssumeRole against that role ARN, supplying the external ID.
The temporary credentials are used to call the Marketplace Catalog API.

This is the same scoped pattern Vellocity uses for agreement sync — least-privilege, read-only against the Catalog API, and revocable by you at any time by detaching the role.

Catalog API: `ListEntities`¶

Discovery calls the Marketplace Catalog ListEntities operation once per entity type and aggregates the results. The entity types map to Vellocity catalog types:

AWS entity type	Vellocity `catalog_type`
`SaaSProduct`	`SAAS`
`AmiProduct`	`AMI`
`ContainerProduct`	`CONTAINER`
`ProfessionalServicesProduct`	`PROF`

For each discovered product Vellocity captures its entity_id, name, visibility, and last_modified.

The three-pass reconcile¶

Each sync run reconciles your AWS catalog against your local listings in three passes (ListingSyncService::syncConnection):

Update existing — Match local listings to AWS products by entity_id. When AWS visibility or last-modified has changed, refresh that metadata and stamp last_synced_at. No listing content is touched.
Auto-link — Recover published-but-unlinked local rows (e.g. from a prior failed entity-id write) by matching on title, then attach the AWS entity_id so they re-link cleanly.
Import new — For every remaining discovered AWS product with no local match, create a new local listing row carrying the title, catalog type, and AWS visibility.

A run returns a count summary: total_aws, matched, updated, auto_linked, and imported.

Your edits are safe

Import never overwrites an existing local row. Listings you or the AI have enriched are preserved across re-syncs — only AWS-side visibility/last-modified metadata is refreshed on matched rows.

Live vs. draft¶

A discovered product whose AWS visibility is Public, Limited, or Restricted is treated as live (imported as published, with published_at set). Anything else — including Draft — is imported as a work-in-progress (complete).

The connect → discover → import → optimize flow¶

Connect AWS account                 → ConnectionController dispatches SyncListingsJob
   ↓
AssumeRole (iam_role_arn +          → cross-account, read-only Catalog API access
external_id)
   ↓
ListEntities (per entity type)      → discover your real AWS Marketplace products
   ↓
3-pass reconcile                    → update existing / auto-link / import new
   ↓
Your listings appear                → metadata-complete local rows, AWS visibility shown
   ↓
Optimize                            → Listing Optimizer + Discovery Dashboard act on them

After sync, your listings are immediately ready for the optimization tools:

Listing Optimizer scores each listing 0–100 across listing quality, backlink authority, and AI visibility.
Discovery Dashboard shows how AI assistants currently surface the listing.
Listing Alignment Grader checks whether your external proof backs the listing before you publish.

What this is not¶

A listing builder. Sync imports listings that already exist in your AWS Marketplace catalog. To create a brand-new listing, use AWS Marketplace Management Portal or a Build tool (Tackle, Suger, Clazar). Vellocity focuses on the Market motion — optimizing and promoting what's already listed.
A scraper. Discovery is the official Catalog API ListEntities operation over an IAM role you grant — not a fetch of your public listing pages.
A content overwrite. Re-syncs refresh AWS metadata only; your enriched content is never replaced.

Plan availability¶

Capability	Starter	Accelerate	Command
Auto-discover & import on connect	✅	✅	✅
Six-hourly metadata re-sync	✅	✅	✅

Listing Sync is part of the AWS connection experience on every paid plan. The downstream optimization tools have their own tier gates — see each feature page.