Manifest schema

Offers validate against offer-manifest.schema.json in the marketplace repo. Required fields include slug, title, summary, offer_type, category, pricing, license, compatibility, trust_level, and at least one releases[] entry with artifact URL, SHA-256 checksum, and size.

Pricing models

pricing.model	Fields	Buyer experience
free	amount_cents: 0	CMS installs immediately; hidden entitlement, no visible key
freemium	Free plan plus paid plans/capabilities	Hidden free entitlement with plan capabilities; paid upgrade uses Stripe
trial	trial_days, optional paid plan	No-card trial entitlement until trial_ends_at; no offline extension past trial end
one_time	amount_cents > 0, currency	Single Stripe payment; entitlement plus fallback activation key per seat tier
subscription	amount_cents > 0, currency, subscription_interval (month / year)	Stripe Billing; entitlement active while subscription active; lapsed subscriptions lose update/install rights after grace

Example subscription block in offer manifest:

"pricing": {
  "model": "subscription",
  "amount_cents": 999,
  "currency": "USD",
  "subscription_interval": "month"
}

Stripe webhooks (customer.subscription.updated, customer.subscription.deleted) update entitlement/license status. CMS update checks call the marketplace status API and block updates when subscription access lapses.

Entitlements and seats

Paid checkout issues an entitlement and a fallback activation key. Free and freemium offers issue hidden entitlements so buyers do not see or copy keys. A signed local entitlement token lets the CMS continue checks during short outages; this is practical deterrence, not perfect DRM.

Single-site tiers allow one production activation plus one staging activation. Buyers can deactivate an old installation to free that environment seat. Multi-site and unlimited tiers follow the seat limits declared on the offer.

Partner keys (complimentary entitlements)

Use Partner keys in Provider Studio when you want to give a friend, agency, or press contact access to a paid or freemium offer without sending them through checkout:

1. Open Partner keys and choose the offer.
2. Optionally set a recipient email, internal note, and expiry date.
3. Generate the key and share it securely — they activate it in Birkly Hub like a purchased key.
4. Revoke the key later if the partnership ends.

Partner keys use the same seat rules as paid purchases. They are audited and count toward a soft monthly limit (default 50 per 30 days; Ops can raise). Pure free catalog offers already install without keys, so partner keys are not issued for those. Prefer partner keys for one-off handoffs; use promo/discount codes when you want a reusable marketing campaign.

Plugin package (plugin.json)

Plugin artifacts are validated against plugin-package.schema.json. Required: name, version, description. Recommended: requires_birkly, requires_php, declared capabilities (least privilege).

Site pack package

Site pack (template_pack) artifacts use the starter/pack layout. QC expects pack manifest.json + collections/ + project/ — a plugin zip fails pack preflight. Buyers install to content/collections/ + project/ (never themes/). See Hub, themes, and site packs.

Registry API

Published offers are exposed at:

• GET /api/v1/registry — catalog index
• GET /api/v1/offer?slug={slug} — offer detail + releases
• GET /api/v1/release?slug={slug}&version={version} — release metadata + download URL

The Birkly CMS Hub client consumes these endpoints; do not break slug or checksum contracts without a major version bump.

Trust levels

Level	Meaning
untrusted	Community listing; automated preflight only
trusted	Passed automated checks; Birkly team may spot-check
verified	Manual technical review for first release and major updates

QC and security

• Zip must not contain path traversal (..).
• PHP files are scanned for dangerous patterns (eval, shell_exec, etc.).
• Declared capabilities should match what the plugin requests at install time.

Revenue

Stripe Connect splits: buyer pays gross price → Stripe fee → Birkly application fee → remainder to your Connect account. The default Birkly application fee is 15%; Ops may override the fee for a provider or agreement. Paid third-party offers can only be sold by providers in Stripe-supported connected-account countries during P55.

Refunds and chargebacks

• Buyers may request refunds within the default 14-day window.
• Providers approve or deny third-party refund requests first; Birkly Ops can escalate under marketplace policy.
• A full refund revokes the entitlement and active activation slots.
• Chargebacks put the entitlement on hold immediately. If the dispute is lost, the entitlement is revoked; if won, Ops may restore access.

GitHub App — automated releases (Phase 12)

Third-party providers can connect a repository so new tags trigger build → preflight → QC enqueue (offers are not auto-published).

1. Install the Birkly Marketplace GitHub App on your repository (organization or user).
2. In Provider dashboard → Connect GitHub repository, enter:

- Installation ID (from GitHub App settings) - Owner and repository name - Offer slug to map releases to - Tag pattern (default v* — matches v1.0.0, v2.1.3, etc.)

1. Publish a GitHub Release or tag matching the pattern.
2. Marketplace webhook POST /webhooks/github verifies the signature, downloads the release asset (or builds from tag archive), runs preflight, and enqueues QC review.
3. After admin approval (verified tier) or automatic pass (trusted/untrusted per policy), the catalog release updates.

Official plugins (Birkly repo)

Raaakete official plugins use CI on tag plugin/{name}/v* → build-all-official-plugin-zips.sh → registry API upload. See Birkly plugins/README.md and Production deploy checklist.

Provider webhooks (optional, Phase 12)

Configure a webhook URL in the provider dashboard to receive JSON events:

Event	When
sale	Buyer completes checkout for your offer
refund	Refund processed
qc_result	Preflight/QC completes
payout	Stripe Connect payout recorded

Verify webhook signatures using the secret shown in the dashboard. Use for internal ERP, Slack, or license fulfillment systems.

Stripe webhooks (platform)

Marketplace operators configure Stripe → POST /webhooks/stripe for account.updated, payment_intent.succeeded, charge.refunded. Provider dashboard payout charts read from Connect APIs.