Marketplace API

The Marketplace API covers two audiences: publishers who build and list apps, and buyers who browse and install them.

Publisher Endpoints

All publisher routes require an authenticated session where the caller is a member of the org that owns the app.

Publish an App

~~~http POST /api/marketplace/apps Authorization: Bearer Content-Type: application/json

{ "name": "DataSync Pro", "slug": "datasync-pro", "description": "Real-time data synchronisation for SaaS teams.", "deployment_modes": ["multi_tenant", "single_tenant"], "pricing_model": "seat", "base_price_cents": 1500, "currency": "usd", "provision_webhook": "https://api.datasync.example/buttrbase/provision" } ~~~

~~~jsonc // 201 Created { "app_id": "app_01abc...", "slug": "datasync-pro", "status": "draft", // held until platform admin approves "webhook_secret": "whs_..." // store this — returned once } ~~~

Update App Metadata

~~~http PATCH /api/marketplace/apps/:app_id ~~~

Accepts any subset of the publish body fields except slug.

Rotate Provision Webhook Secret

~~~http POST /api/marketplace/apps/:app_id/webhook/rotate ~~~

Returns a new webhook_secret. Update your provision endpoint immediately — the old secret is invalidated.

List Your Apps

~~~http GET /api/marketplace/apps ~~~

Returns all apps owned by the caller's org including draft and archived.

View Installs for Your App

~~~http GET /api/marketplace/apps/:app_id/installs GET /api/marketplace/apps/:app_id/installs/:install_id ~~~

Add a Marketplace Listing

~~~http POST /api/marketplace/apps/:app_id/listings

{ "marketplace": "aws", "external_product_id": "prod-abc123", "external_plan_id": "plan-pro" } ~~~

---

Buyer Endpoints

Browse the Marketplace

~~~http GET /api/marketplace GET /api/marketplace?q=datasync ~~~

~~~jsonc // 200 OK { "apps": [ { "app_id": "app_01abc...", "name": "DataSync Pro", "slug": "datasync-pro", "description": "...", "pricing_model": "seat", "base_price_cents": 1500, "deployment_modes": ["multi_tenant", "single_tenant"] } ], "total": 42, "page": 1 } ~~~

App Detail

~~~http GET /api/marketplace/:slug ~~~

Install an App

~~~http POST /api/marketplace/:slug/install Authorization: Bearer Content-Type: application/json

{ "deployment_mode": "single_tenant", "plan_id": "pro", "quantity": 1 } ~~~

~~~jsonc // 202 Accepted { "install_id": "inst_01def...", "status": "provisioning" } ~~~

ButtrBase immediately calls the publisher's provision webhook. Poll GET /api/installs/:id until status becomes active.

My Installs

~~~http GET /api/installs GET /api/installs/:install_id ~~~

~~~jsonc { "install_id": "inst_01def...", "app": { "name": "DataSync Pro", "slug": "datasync-pro" }, "status": "active", "deployment_mode": "single_tenant", "endpoint_url": "https://acme.datasync.example", "payment_source": "direct", "current_period_end": "2026-06-17T00:00:00Z" } ~~~

Deprovision an Install

~~~http DELETE /api/installs/:install_id ~~~

Triggers install.deprovisioning webhook event. Status transitions to deprovisioning then deprovisioned once the publisher acknowledges.

---

App Admin Grant Endpoints

~~~http GET /api/marketplace/apps/:app_id/admins POST /api/marketplace/apps/:app_id/admins DELETE /api/marketplace/apps/:app_id/admins/:user_id ~~~

See the App Admin API for details.