Managing Published Packages

Publishing a New Version

To update a package, submit a new version through the standard submission endpoint with an incremented SemVer version. The new version enters the review pipeline independently.

POST /api/marketplace/submit
// Same as initial submission — increment the version in manifest.json
// The packageId in manifest must match the existing marketplace packageId

// After the new version is listed:
// - New installs receive the latest version
// - Existing installs remain on their pinned version
// - Tenants subscribed to update notifications receive an in-app alert

Updating Package Metadata

Marketplace metadata (description, screenshots, tags) can be updated without resubmitting the package. Metadata updates do not require a new review.

PATCH /api/marketplace/packages/{packageId}
Authorization: Bearer {publisherToken}
{
  "description": "Updated description with improved clarity.",
  "tags":        ["onboarding", "hr", "approval", "parallel-approvals"],
  "screenshots": [
    { "url": "https://acmecorp.com/screenshots/v3-flow.png", "caption": "v3.0 parallel approval flow" }
  ]
}

// Response:
{
  "packageId":   "mkt-pkg-a1b2c3",
  "updatedAt":   "2026-05-25T15:00:00Z",
  "updatedFields": ["description", "tags", "screenshots"]
}

Deprecating a Version

Deprecating a version warns current installers without removing access. Use deprecation when a version has known issues and you want to guide users to a newer version.

POST /api/marketplace/packages/{packageId}/versions/{version}/deprecate
Authorization: Bearer {publisherToken}
{
  "reason":            "Critical bug in approval escalation logic — upgrade to 3.0.1 or later.",
  "replacedByVersion": "3.0.1"
}

// Effect:
// - Version marked as deprecated in marketplace
// - Tenants with this version installed receive an urgent update notification
// - Deprecated versions cannot be freshly installed — new installs use latest non-deprecated version
// - Deprecated versions remain downloadable for tenants who have them pinned

Unlisting a Package

Unlisting removes a package from marketplace discovery. Existing installations continue to work, and existing installs can still download their pinned version. Unlisting cannot be reversed without a new submission review.

POST /api/marketplace/packages/{packageId}/unlist
Authorization: Bearer {publisherToken}
{
  "reason": "Package superseded by 'acme-corp/onboarding-v2' which includes all functionality."
}

// Response:
{
  "packageId":   "mkt-pkg-a1b2c3",
  "status":      "Unlisted",
  "unlistedAt":  "2026-05-25T16:00:00Z",
  "message":     "Package removed from search results. Existing installations remain functional."
}

Version State Summary

Viewing Install Analytics

GET /api/marketplace/packages/{packageId}/analytics?period=30d

{
  "packageId":      "mkt-pkg-a1b2c3",
  "period":         "30d",
  "totalInstalls":  847,
  "newInstalls":    63,
  "activeVersions": {
    "3.0.0": 312,
    "2.2.0": 480,
    "2.1.0": 55
  },
  "installsByDay": [
    { "date": "2026-05-01", "count": 2 },
    { "date": "2026-05-02", "count": 5 }
  ],
  "topInstallerRegions": ["US", "EU", "APAC"]
}

Publisher Dashboard Summary

GET /api/marketplace/publishers/{publisherId}/dashboard

{
  "publisherId":    "pub-a1b2c3",
  "totalPackages":  12,
  "listedPackages": 10,
  "totalInstalls":  4821,
  "averageRating":  4.7,
  "pendingSubmissions": 1,
  "packages": [
    {
      "packageId":    "mkt-pkg-a1b2c3",
      "name":         "Employee Onboarding",
      "trustLevel":   "Certified",
      "installs":     847,
      "rating":       4.8,
      "latestVersion": "3.0.0"
    }
  ]
}